jetemail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5689f2bfdd4487a75d88fb2bf22b02abaf3d99f318a268093544cd9ae58fc3ee
+  data.tar.gz: 96b236ee47f7a9724d2bcd610c626c73309e715aa9b0b57766fe93be3869c3c3
+SHA512:
+  metadata.gz: f1bcb138b5ffc80f2009b362f5993375d47e1bbe51bb8b65641425c1e40029b1b398a2be084d04e0be213107c5f158247ba0cb1190dbb27fbca483c7b88bf6c7
+  data.tar.gz: 21db98dd2d350d67dd4b0d56d27390b238b49a8c731fb0d4e779c9782f77dd65f338269c5510ef3de22ca1b5fde6d8fa58fa34b1c411dc7d40106c8205735697

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- Send single emails via `JetEmail::Emails.send`
+- Send batch emails via `JetEmail::Batch.send`
+- Webhooks CRUD: list, get, create, update, remove, query, replay
+- Webhook signature verification via `JetEmail::Webhooks.verify`
+- Rails ActionMailer integration
+- Error handling with typed exceptions and rate limit support

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JetEmail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,204 @@
+# JetEmail Ruby SDK
+
+Ruby SDK for the [JetEmail](https://jetemail.com) transactional email service.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "jetemail"
+```
+
+Then run `bundle install`. Or install directly:
+
+```
+gem install jetemail
+```
+
+## Configuration
+
+```ruby
+require "jetemail"
+
+JetEmail.configure do |config|
+  config.api_key = "transactional_your_key_here"
+end
+```
+
+Or set the `JETEMAIL_API_KEY` environment variable and configure in an initializer.
+
+## Sending Emails
+
+### Single Email
+
+```ruby
+JetEmail::Emails.send({
+  from: "App <hello@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Welcome!",
+  html: "<h1>Hello</h1><p>Welcome to our app.</p>"
+})
+# => { id: "msg_123", response: "Queued" }
+```
+
+### With Attachments
+
+```ruby
+JetEmail::Emails.send({
+  from: "App <hello@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Your invoice",
+  html: "<p>Please find your invoice attached.</p>",
+  attachments: [
+    { filename: "invoice.pdf", data: Base64.strict_encode64(File.read("invoice.pdf")) }
+  ]
+})
+```
+
+### All Options
+
+```ruby
+JetEmail::Emails.send({
+  from: "App <hello@yourdomain.com>",
+  to: ["user1@example.com", "user2@example.com"],  # max 50
+  subject: "Hello",
+  html: "<h1>Hello</h1>",
+  text: "Hello",                                     # plain text fallback
+  cc: "cc@example.com",                              # string or array, max 50
+  bcc: ["bcc1@example.com"],                         # string or array, max 50
+  reply_to: "reply@example.com",                     # string or array, max 50
+  headers: { "X-Custom-Header" => "value" },
+  attachments: [{ filename: "file.txt", data: "base64..." }],
+  eu: true                                           # EU-only delivery
+})
+```
+
+### Batch Email
+
+Send up to 100 emails in a single request:
+
+```ruby
+JetEmail::Batch.send([
+  {
+    from: "App <hello@yourdomain.com>",
+    to: "user1@example.com",
+    subject: "Hello User 1",
+    html: "<p>Hi User 1</p>"
+  },
+  {
+    from: "App <hello@yourdomain.com>",
+    to: "user2@example.com",
+    subject: "Hello User 2",
+    html: "<p>Hi User 2</p>"
+  }
+])
+# => { summary: { total: 2, successful: 2, failed: 0 }, results: [...] }
+```
+
+## Webhooks
+
+### CRUD Operations
+
+```ruby
+# List all webhooks
+JetEmail::Webhooks.list
+
+# Get a webhook
+JetEmail::Webhooks.get("webhook_uuid")
+
+# Create a webhook
+JetEmail::Webhooks.create({
+  name: "My Webhook",
+  url: "https://example.com/webhook",
+  events: ["outbound.delivered", "outbound.bounced"]
+})
+
+# Update a webhook
+JetEmail::Webhooks.update({ uuid: "webhook_uuid", name: "Updated Name" })
+
+# Delete a webhook
+JetEmail::Webhooks.remove("webhook_uuid")
+
+# Query webhook events
+JetEmail::Webhooks.query({ uuid: "webhook_uuid", event_type: "outbound.delivered" })
+
+# Replay a webhook event
+JetEmail::Webhooks.replay({ event_id: "event_123" })
+```
+
+### Webhook Event Types
+
+**Outbound:** `outbound.queued`, `outbound.delivered`, `outbound.bounced`, `outbound.rejected`, `outbound.deferred`, `outbound.spam`, `outbound.dropped`, `outbound.virus`, `outbound.opened`, `outbound.clicked`, `outbound.complaint`
+
+### Signature Verification
+
+Verify incoming webhook requests using the `X-Webhook-Signature`, `X-Webhook-Timestamp`, and your webhook secret:
+
+```ruby
+JetEmail::Webhooks.verify(
+  payload: request.raw_post,
+  signature: request.headers["X-Webhook-Signature"],
+  timestamp: request.headers["X-Webhook-Timestamp"],
+  secret: ENV["JETEMAIL_WEBHOOK_SECRET"]
+)
+# => true (or raises JetEmail::Error)
+```
+
+## Rails Integration
+
+The gem integrates with Rails ActionMailer automatically.
+
+### Setup
+
+In `config/environments/production.rb`:
+
+```ruby
+config.action_mailer.delivery_method = :jetemail
+```
+
+In an initializer (`config/initializers/jetemail.rb`):
+
+```ruby
+JetEmail.configure do |config|
+  config.api_key = ENV["JETEMAIL_API_KEY"]
+end
+```
+
+### Usage
+
+Use ActionMailer as normal:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome(user)
+    mail(
+      from: "App <hello@yourdomain.com>",
+      to: user.email,
+      subject: "Welcome!"
+    )
+  end
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  JetEmail::Emails.send({ from: "a@b.com", to: "c@d.com", subject: "Hi", text: "Hello" })
+rescue JetEmail::Error::RateLimitError => e
+  puts "Rate limited. Retry after: #{e.retry_after}s"
+rescue JetEmail::Error::InvalidRequestError => e
+  puts "Invalid request: #{e.message} (#{e.status_code})"
+rescue JetEmail::Error::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue JetEmail::Error::InternalServerError => e
+  puts "Server error: #{e.message}"
+rescue JetEmail::Error => e
+  puts "Error: #{e.message} (#{e.status_code})"
+end
+```
+
+## License
+
+MIT

data/lib/jetemail/batch.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module JetEmail
+  module Batch
+    class << self
+      # Send a batch of up to 100 emails.
+      #
+      # @param emails [Array<Hash>] Array of email parameter hashes (same schema as Emails.send)
+      # @return [Hash] Response with :summary and :results keys
+      def send(emails = [])
+        path = "email-batch"
+        JetEmail::Request.new(path, { emails: emails }, "post").perform
+      end
+    end
+  end
+end

data/lib/jetemail/emails.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module JetEmail
+  module Emails
+    class << self
+      # Send a single email.
+      #
+      # @param params [Hash] Email parameters
+      # @option params [String] :from Required. Sender in "Name <email>" format
+      # @option params [String, Array<String>] :to Required. Recipient(s), max 50
+      # @option params [String] :subject Required. Email subject
+      # @option params [String] :html HTML body (at least one of html/text required)
+      # @option params [String] :text Plain text body
+      # @option params [String, Array<String>] :cc CC recipient(s), max 50
+      # @option params [String, Array<String>] :bcc BCC recipient(s), max 50
+      # @option params [String, Array<String>] :reply_to Reply-to address(es), max 50
+      # @option params [Hash] :headers Custom email headers
+      # @option params [Array<Hash>] :attachments File attachments (base64-encoded)
+      # @option params [Boolean] :eu EU-only delivery
+      # @return [Hash] Response with :id and :response keys
+      def send(params)
+        path = "email"
+        JetEmail::Request.new(path, params, "post").perform
+      end
+    end
+  end
+end

data/lib/jetemail/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module JetEmail
+  class Error < StandardError
+    ClientError = Class.new(self)
+    ServerError = Class.new(self)
+    InternalServerError = Class.new(ServerError)
+    InvalidRequestError = Class.new(ClientError)
+
+    class RateLimitError < ClientError
+      attr_reader :retry_after
+
+      def initialize(msg, code = nil, headers = {})
+        super(msg, code, headers)
+        @retry_after = headers["retry-after"]&.to_i
+      end
+    end
+
+    NotFoundError = Class.new(ClientError)
+
+    ERRORS = {
+      400 => InvalidRequestError,
+      401 => InvalidRequestError,
+      403 => InvalidRequestError,
+      404 => NotFoundError,
+      422 => InvalidRequestError,
+      429 => RateLimitError,
+      500 => InternalServerError
+    }.freeze
+
+    attr_reader :status_code, :headers
+
+    def initialize(msg, code = nil, headers = {})
+      super(msg)
+      @status_code = code
+      @headers = headers || {}
+    end
+  end
+end

data/lib/jetemail/mailer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "jetemail"
+
+module JetEmail
+  class Mailer
+    attr_accessor :config, :settings
+
+    IGNORED_HEADERS = %w[
+      from to cc bcc subject reply-to
+      mime-version content-type content-transfer-encoding
+      date message-id
+    ].freeze
+
+    def initialize(config)
+      @config = config
+      raise JetEmail::Error.new("API key is not set") unless JetEmail.api_key
+
+      @settings = { return_response: true }
+    end
+
+    def deliver!(mail)
+      params = build_params(mail)
+      resp = JetEmail::Emails.send(params)
+      mail.message_id = resp[:id] if resp[:id]
+      resp
+    end
+
+    private
+
+    def build_params(mail)
+      params = {
+        from: get_from(mail),
+        to: mail.to,
+        subject: mail.subject
+      }
+
+      params[:cc] = mail.cc if mail.cc&.any?
+      params[:bcc] = mail.bcc if mail.bcc&.any?
+      params[:reply_to] = mail.reply_to if mail.reply_to&.any?
+
+      params.merge!(get_contents(mail))
+
+      headers = get_headers(mail)
+      params[:headers] = headers unless headers.empty?
+
+      attachments = get_attachments(mail)
+      params[:attachments] = attachments if attachments.any?
+
+      params
+    end
+
+    def get_from(mail)
+      return mail.from.first if mail[:from].nil?
+
+      from = mail[:from].formatted
+      return from.first if from.is_a?(Array)
+
+      from.to_s
+    end
+
+    def get_contents(mail)
+      params = {}
+      case mail.mime_type
+      when "text/plain"
+        params[:text] = mail.body.decoded
+      when "text/html"
+        params[:html] = mail.body.decoded
+      when "multipart/alternative", "multipart/mixed", "multipart/related"
+        params[:text] = mail.text_part.decoded if mail.text_part
+        params[:html] = mail.html_part.decoded if mail.html_part
+      end
+      params
+    end
+
+    def get_headers(mail)
+      headers = {}
+      mail.header_fields.each do |field|
+        next if IGNORED_HEADERS.include?(field.name.downcase)
+
+        headers[field.name] = field.unparsed_value
+      end
+      headers
+    end
+
+    def get_attachments(mail)
+      mail.attachments.map do |part|
+        headers = part.respond_to?(:header) ? part.header : nil
+        filename = part.filename || "attachment"
+        {
+          filename: filename,
+          data: Base64.strict_encode64(part.body.decoded)
+        }
+      end
+    end
+  end
+end

data/lib/jetemail/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "jetemail"
+require "jetemail/mailer"
+
+module JetEmail
+  class Railtie < ::Rails::Railtie
+    ActiveSupport.on_load(:action_mailer) do
+      add_delivery_method :jetemail, JetEmail::Mailer
+      ActiveSupport.run_load_hooks(:jetemail_mailer, JetEmail::Mailer)
+    end
+  end
+end

data/lib/jetemail/request.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module JetEmail
+  class Request
+    BASE_URL = ENV["JETEMAIL_BASE_URL"] || "https://api.jetemail.com"
+
+    attr_accessor :body, :verb
+
+    def initialize(path = "", body = {}, verb = "post")
+      raise JetEmail::Error.new("API key is not set") if JetEmail.api_key.nil?
+
+      api_key = JetEmail.api_key
+      api_key = api_key.call if api_key.is_a?(Proc)
+
+      @path = path
+      @body = body
+      @verb = verb
+      @headers = {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => "jetemail-ruby:#{JetEmail::VERSION}",
+        "Authorization" => "Bearer #{api_key}"
+      }
+    end
+
+    def perform
+      options = build_options
+      resp = HTTParty.send(@verb.to_sym, "#{BASE_URL}/#{@path}", options)
+
+      data = parse_response(resp)
+      handle_error!(data, resp) if error_response?(resp)
+      data
+    end
+
+    private
+
+    def build_options
+      options = { headers: @headers }
+
+      if @verb.downcase == "get" && !@body.empty?
+        options[:query] = @body
+      elsif !@body.empty?
+        options[:body] = @body.to_json
+      end
+
+      options
+    end
+
+    def parse_response(resp)
+      return {} if resp.body.nil? || resp.body.empty?
+
+      JSON.parse(resp.body, symbolize_names: true)
+    rescue JSON::ParserError
+      raise JetEmail::Error::InternalServerError.new("Unexpected response from JetEmail API", resp.code)
+    end
+
+    def error_response?(resp)
+      resp.code >= 400
+    end
+
+    def handle_error!(data, resp)
+      raw_headers = resp.respond_to?(:headers) ? resp.headers.to_h : {}
+      headers = raw_headers.transform_values { |v| v.is_a?(Array) ? v.last : v }
+      message = data[:message] || data[:error] || "Request failed with status #{resp.code}"
+      error_class = JetEmail::Error::ERRORS[resp.code] || JetEmail::Error
+      raise error_class.new(message, resp.code, headers)
+    end
+  end
+end

data/lib/jetemail/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JetEmail
+  VERSION = "0.1.0"
+end

data/lib/jetemail/webhooks.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module JetEmail
+  WEBHOOK_TOLERANCE_SECONDS = 300
+
+  module Webhooks
+    class << self
+      # List all webhooks.
+      #
+      # @return [Hash] List of webhooks
+      def list
+        path = "webhooks"
+        JetEmail::Request.new(path, {}, "get").perform
+      end
+
+      # Get a single webhook.
+      #
+      # @param uuid [String] Webhook UUID
+      # @return [Hash] Webhook details
+      def get(uuid)
+        path = "webhooks/#{uuid}"
+        JetEmail::Request.new(path, {}, "get").perform
+      end
+
+      # Create a webhook.
+      #
+      # @param params [Hash] Webhook parameters
+      # @option params [String] :name Required. Webhook name
+      # @option params [String] :url Required. Webhook URL
+      # @option params [Array<String>] :events Required. Event types to subscribe to
+      # @return [Hash] Created webhook
+      def create(params)
+        path = "webhooks"
+        JetEmail::Request.new(path, params, "post").perform
+      end
+
+      # Update a webhook.
+      #
+      # @param params [Hash] Webhook parameters
+      # @option params [String] :uuid Required. Webhook UUID
+      # @return [Hash] Updated webhook
+      def update(params)
+        path = "webhooks"
+        JetEmail::Request.new(path, params, "patch").perform
+      end
+
+      # Delete a webhook.
+      #
+      # @param uuid [String] Webhook UUID
+      # @return [Hash] Deletion confirmation
+      def remove(uuid)
+        path = "webhooks/#{uuid}"
+        JetEmail::Request.new(path, {}, "delete").perform
+      end
+
+      # Query webhook events.
+      #
+      # @param params [Hash] Query filters
+      # @return [Hash] Matching webhook events
+      def query(params = {})
+        path = "webhooks/query"
+        JetEmail::Request.new(path, params, "post").perform
+      end
+
+      # Replay a webhook event.
+      #
+      # @param params [Hash] Replay parameters
+      # @option params [String] :event_id Event ID to replay
+      # @option params [String] :source_uid Source UID to replay
+      # @return [Hash] Replay confirmation
+      def replay(params)
+        path = "webhooks/replay"
+        JetEmail::Request.new(path, params, "post").perform
+      end
+
+      # Verify a webhook signature.
+      #
+      # @param payload [String] Raw request body
+      # @param signature [String] X-Webhook-Signature header value
+      # @param timestamp [String] X-Webhook-Timestamp header value
+      # @param secret [String] Your webhook secret
+      # @param tolerance [Integer] Max age in seconds (default: 300)
+      # @return [Boolean] true if valid
+      # @raise [JetEmail::Error] if verification fails
+      def verify(payload:, signature:, timestamp:, secret:, tolerance: WEBHOOK_TOLERANCE_SECONDS)
+        raise JetEmail::Error.new("Payload cannot be empty") if payload.nil? || payload.empty?
+        raise JetEmail::Error.new("Signature cannot be empty") if signature.nil? || signature.empty?
+        raise JetEmail::Error.new("Timestamp cannot be empty") if timestamp.nil? || timestamp.to_s.empty?
+        raise JetEmail::Error.new("Secret cannot be empty") if secret.nil? || secret.empty?
+
+        ts = timestamp.to_i
+        diff = (Time.now.to_i - ts).abs
+        if tolerance > 0 && diff > tolerance
+          raise JetEmail::Error.new("Webhook timestamp is outside tolerance (#{diff}s)")
+        end
+
+        expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+        unless secure_compare(expected, signature)
+          raise JetEmail::Error.new("Webhook signature verification failed")
+        end
+
+        true
+      end
+
+      private
+
+      def secure_compare(a, b)
+        return false if a.nil? || b.nil? || a.bytesize != b.bytesize
+
+        bytes_a = a.unpack("C*")
+        result = 0
+        b.each_byte.with_index { |byte, i| result |= byte ^ bytes_a[i] }
+        result.zero?
+      end
+    end
+  end
+end

data/lib/jetemail.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+require "jetemail/version"
+require "jetemail/errors"
+require "jetemail/request"
+require "jetemail/emails"
+require "jetemail/batch"
+require "jetemail/webhooks"
+
+require "jetemail/railtie" if defined?(Rails) && defined?(ActionMailer)
+
+module JetEmail
+  class << self
+    attr_accessor :api_key
+
+    def configure
+      yield self if block_given?
+      true
+    end
+    alias_method :config, :configure
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: jetemail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JetEmail
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Ruby SDK for the JetEmail transactional email service.
+email: support@jetemail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/jetemail.rb
+- lib/jetemail/batch.rb
+- lib/jetemail/emails.rb
+- lib/jetemail/errors.rb
+- lib/jetemail/mailer.rb
+- lib/jetemail/railtie.rb
+- lib/jetemail/request.rb
+- lib/jetemail/version.rb
+- lib/jetemail/webhooks.rb
+homepage: https://github.com/jetemail/jetemail-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jetemail/jetemail-ruby
+  source_code_uri: https://github.com/jetemail/jetemail-ruby
+  changelog_uri: https://github.com/jetemail/jetemail-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/jetemail/jetemail-ruby/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: The Ruby and Rails SDK for jetemail.com
+test_files: []