mailkite 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6150a49b6aeb81a4a2f47110dca45c08d0369de7492de5f09a93ba962aae6e22
-  data.tar.gz: 7432bb5749a2e701d4a08cbaf92e0a386853e9953c7b4db4cfb23834f480c96d
+  metadata.gz: 1271ec234bd17506cc9aa35f15262d7708bb827786df2da37065457b90e0f106
+  data.tar.gz: 490ce824dc5ff8097190a893db918f906945c4239822387a9e39f10e4fa85f29
 SHA512:
-  metadata.gz: e8651f3331f64a40afca30a2b3191d40deb9a9cf71393e8d9df8a1ae9273ad5d73828dc67b38a3f928d80b063ed32c03e337f418a7df1646eb0806dcbb70862c
-  data.tar.gz: d8989b2cc0b1581990b0b4c0c1622e65fc89b9acec5ad26e4de734b583354fd777f779072d696d84cf267457e9a415c2b57c470872417c138caec224e6e13272
+  metadata.gz: 621ff2176d573d2df21262f249e018b5e0acce0ab79d296ecc40ee9e2e5d031c60009bd7514ea292fa9bb4a76183ceecbb4d573837e6388b3194e8b4231bd167
+  data.tar.gz: 3515d606332f77ba60b3304f0d7945cf3e4cfaf77799ea719b9a3d6b20c9f3736f7bb12152020b3d5d31a35ce4a84157e3c5e4418467015d5d5861fc43262e84

data/lib/mailkite/delivery_method.rb

@@ -0,0 +1,150 @@
+# Docs: docs/integrations/rails-delivery-method.md
+#
+# ActionMailer / Mail delivery method: deliver Mail::Message objects through
+# the MailKite API (POST /v1/send) instead of SMTP.
+#
+#   # Rails — the Railtie registers :mailkite automatically:
+#   config.action_mailer.delivery_method = :mailkite
+#   config.action_mailer.mailkite_settings = { api_key: ENV["MAILKITE_API_KEY"] }
+#
+#   # Plain Mail (no Rails):
+#   Mail.defaults { delivery_method Mailkite::DeliveryMethod, api_key: ENV["MAILKITE_API_KEY"] }
+#
+# The `mail` gem is NOT a runtime dependency of this gem — it is required
+# lazily here, on instantiation, so `require "mailkite"` stays zero-dependency.
+
+module Mailkite
+  class DeliveryMethod
+    # Raised when a Mail::Message uses a feature the send API has no
+    # equivalent for (custom headers, inline cid: attachments, …). Refusing
+    # loudly beats silently dropping part of the message.
+    class UnsupportedFeatureError < StandardError; end
+
+    # Top-level headers the conversion consumes, plus the structural headers
+    # that only describe the MIME document (the API composes its own MIME).
+    # Anything else raises UnsupportedFeatureError — POST /v1/send takes no
+    # custom headers.
+    HANDLED_HEADERS = %w[
+      from to cc bcc subject reply-to in-reply-to
+      date message-id mime-version content-type content-transfer-encoding
+    ].freeze
+
+    attr_reader :settings
+
+    # settings: api_key (falls back to ENV["MAILKITE_API_KEY"]), optional
+    # base_url, or bring your own `client` — anything with `send(message)`
+    # (e.g. a Mailkite::Client, or a stub in tests). Takes precedence over
+    # api_key.
+    def initialize(settings = {})
+      require "mail" # lazy — only delivery-method users need the mail gem
+      @settings = settings
+      @client = settings[:client]
+      return if @client
+
+      api_key = settings[:api_key] || ENV["MAILKITE_API_KEY"]
+      if api_key.nil? || api_key.empty?
+        raise ArgumentError, "MailKite API key missing — pass api_key: in mailkite_settings or set MAILKITE_API_KEY"
+      end
+      @client = Client.new(api_key, settings[:base_url] || DEFAULT_BASE_URL)
+    end
+
+    # Deliver a Mail::Message via POST /v1/send. Returns the API response hash
+    # ({ "id" => …, "status" => … }); API failures raise Mailkite::Error.
+    def deliver!(mail)
+      @client.send(payload_for(mail))
+    end
+
+    private
+
+    # Convert a Mail::Message into a send-request body
+    # (sdks/spec/schemas/send-request.json). Raises on anything the API can't
+    # express rather than delivering a lossy message.
+    def payload_for(mail)
+      reject_custom_headers(mail)
+
+      from = addresses(mail[:from]).first
+      raise ArgumentError, "mail is missing a from address" if from.nil?
+      to = addresses(mail[:to])
+      raise ArgumentError, "mail is missing to recipients" if to.empty?
+
+      payload = { "from" => from, "to" => to }
+      cc = addresses(mail[:cc])
+      payload["cc"] = cc unless cc.empty?
+      bcc = addresses(mail[:bcc])
+      payload["bcc"] = bcc unless bcc.empty?
+      payload["subject"] = mail.subject unless mail.subject.nil?
+
+      reply_to = addresses(mail[:reply_to])
+      payload["replyTo"] = reply_to.join(", ") unless reply_to.empty?
+      in_reply_to = Array(mail.in_reply_to)
+      unless in_reply_to.empty?
+        payload["inReplyTo"] = in_reply_to.map { |id| id.start_with?("<") ? id : "<#{id}>" }.join(" ")
+      end
+
+      payload.merge(body_fields(mail)).merge(attachment_fields(mail))
+    end
+
+    # html/text from the message body: html_part/text_part when multipart,
+    # else the body under its own mime type. Any leftover MIME part that is
+    # neither the body nor an attachment has no API equivalent → raise.
+    def body_fields(mail)
+      fields = {}
+      if mail.multipart?
+        html = mail.html_part
+        text = mail.text_part
+        fields["html"] = html.decoded if html
+        fields["text"] = text.decoded if text
+        consumed = [html, text].compact + mail.attachments.to_a
+        leftover = mail.all_parts.reject { |p| p.multipart? || consumed.any? { |c| c.equal?(p) } }
+        unless leftover.empty?
+          raise UnsupportedFeatureError,
+            "the MailKite send API cannot express the #{leftover.first.mime_type} MIME part — only html/text bodies and attachments are supported"
+        end
+      else
+        body = mail.body.decoded
+        unless body.empty?
+          fields[mail.mime_type == "text/html" ? "html" : "text"] = body
+        end
+      end
+      fields
+    end
+
+    # Attachments become { filename, content: base64, contentType }. Inline
+    # (cid:) parts raise — the API has no Content-ID support, so embedded
+    # images would render broken.
+    def attachment_fields(mail)
+      return {} if mail.attachments.empty?
+
+      list = mail.attachments.map do |part|
+        if part.inline?
+          raise UnsupportedFeatureError,
+            "inline (cid:) attachments are not supported by the MailKite send API — attach the file normally or host the image at a URL"
+        end
+        {
+          "filename" => part.filename,
+          "content" => Base64.strict_encode64(part.body.decoded),
+          "contentType" => part.mime_type,
+        }
+      end
+      { "attachments" => list }
+    end
+
+    # POST /v1/send takes no custom headers (the schema is
+    # additionalProperties: false) — refuse them instead of silently dropping.
+    def reject_custom_headers(mail)
+      mail.header.fields.each do |field|
+        name = field.name.to_s.downcase
+        next if HANDLED_HEADERS.include?(name)
+
+        raise UnsupportedFeatureError,
+          "the MailKite send API has no support for the #{field.name} header — remove it, or deliver this message over SMTP relay instead"
+      end
+    end
+
+    # Formatted addresses for a header field (display names kept — the API
+    # parses RFC 5322 mailboxes); [] when the field is absent.
+    def addresses(field)
+      field.nil? ? [] : Array(field.formatted)
+    end
+  end
+end

data/lib/mailkite/railtie.rb

@@ -0,0 +1,16 @@
+# Docs: docs/integrations/rails-delivery-method.md
+#
+# Rails glue: registers :mailkite as an ActionMailer delivery method, so
+#   config.action_mailer.delivery_method = :mailkite
+# just works. Loaded from lib/mailkite.rb only when Rails is present; outside
+# Rails, register Mailkite::DeliveryMethod on `mail` directly.
+
+module Mailkite
+  class Railtie < ::Rails::Railtie
+    initializer "mailkite.add_delivery_method", before: "action_mailer.set_configs" do
+      ActiveSupport.on_load(:action_mailer) do
+        ActionMailer::Base.add_delivery_method :mailkite, Mailkite::DeliveryMethod
+      end
+    end
+  end
+end

data/lib/mailkite.rb

@@ -15,7 +15,7 @@ require "base64"
 require "cgi"
 
 module Mailkite
-  VERSION = "0.11.0"
+  VERSION = "0.13.0"
   DEFAULT_BASE_URL = "https://api.mailkite.dev"
   # Reject webhook events older than this (ms) to block replays. Pass 0 to disable.
   DEFAULT_TOLERANCE_MS = 5 * 60 * 1000
@@ -151,16 +151,28 @@ module Mailkite
       "DELETE" => Net::HTTP::Delete,
     }.freeze
 
-    def initialize(api_key, base_url = DEFAULT_BASE_URL)
-      @api_key = api_key
+    # Authenticate with a Bearer token. `api_key` (mk_live_…) and the `access_token:` keyword (an
+    # OAuth access token) are equivalent — both are Bearer credentials. For short-lived OAuth
+    # tokens pass `get_token:` — a callable invoked before each request for a fresh token (it wins):
+    #   MailKite::Client.new("mk_live_...")
+    #   MailKite::Client.new(access_token: my_oauth_token)
+    #   MailKite::Client.new(get_token: -> { current_session.access_token })
+    def initialize(api_key = nil, base_url = DEFAULT_BASE_URL, access_token: nil, get_token: nil)
+      @api_key = api_key.nil? ? access_token : api_key
+      @get_token = get_token
       @base_url = base_url.sub(%r{/+\z}, "")
     end
 
+    # The Bearer token for one request: a fresh one from get_token if set, else the static key/token.
+    def token
+      @get_token ? @get_token.call : @api_key
+    end
+
     # Low-level request. Every method below is a one-liner on top of this.
     def request(method, path, body = nil)
       uri = URI(@base_url + path)
       req = VERBS.fetch(method).new(uri)
-      req["Authorization"] = "Bearer #{@api_key}"
+      req["Authorization"] = "Bearer #{token}"
       unless body.nil?
         req["Content-Type"] = "application/json"
         req.body = JSON.generate(body)
@@ -178,7 +190,7 @@ module Mailkite
       qs = query.map { |k, v| "#{CGI.escape(k)}=#{CGI.escape(v.to_s)}" }.join("&")
       uri = URI("#{@base_url}/v1/attachments?#{qs}")
       req = Net::HTTP::Post.new(uri)
-      req["Authorization"] = "Bearer #{@api_key}"
+      req["Authorization"] = "Bearer #{token}"
       req["Content-Type"] = content_type
       req.body = bytes
       perform(req, uri)
@@ -337,6 +349,10 @@ module Mailkite
       request("POST", "/api/routes", body)
     end
 
+    def deleteRoute(id)
+      request("DELETE", "/api/routes/#{id}")
+    end
+
     # --- Templates ------------------------------------------------------
     def listTemplates
       request("GET", "/api/templates")
@@ -476,3 +492,8 @@ module Mailkite
     end
   end
 end
+
+# ActionMailer / Mail integration (config.action_mailer.delivery_method = :mailkite).
+# The `mail` gem is not a runtime dependency — DeliveryMethod requires it lazily.
+require_relative "mailkite/delivery_method"
+require_relative "mailkite/railtie" if defined?(::Rails::Railtie)

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: mailkite
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - MailKite
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
-dependencies: []
+date: 2026-07-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
 description: Send and manage email over your own authenticated domain with MailKite.
 email:
 executables: []
@@ -17,6 +31,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/mailkite.rb
+- lib/mailkite/delivery_method.rb
+- lib/mailkite/railtie.rb
 homepage: https://mailkite.dev/docs/libraries
 licenses:
 - MIT