mailkite 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12f2253d7e19c077b589585febf6c7fc997c8638d7feaad9027afd34ad2a1f04
-  data.tar.gz: 8a81bf20948fc4c48b0d3abea045c56683062521fe1b3fe6d02b8e36bd31a06c
+  metadata.gz: 26eb50d856d1ba16356a5fc399a84414774dccf715a0dc6291b451030ea27272
+  data.tar.gz: 3472e6b74b0772e5c18906fb66e9fd8c39dcb6de194fbf1a78b131086d676d3c
 SHA512:
-  metadata.gz: bc93387f841f8a0a6e5d5a2da37587bd4637392195b5d9a63646f924006326a4a6ad2e46a06bc4157008efd9515a7f35b861d193ea89ffae9cff455107b7da0b
-  data.tar.gz: 6b0293d9b75d5ebdd4decf62ea93b2be18b283cf7162062c125cdffff6b8dc0d2c927bca6bbd09bdc880696938a96b5811b2d652caf3490a26378af7790a1278
+  metadata.gz: ca926ae3006b0fde3931988b8e1cb62f196831e60bf9e3d77cf5b0b10ba8dd724858ef1428a3decc422787e166e876c471605e04384880c1030e209f6dca5420
+  data.tar.gz: ae7bcbefece087b52e9936df73b885a63a4e264b6b05d0b6b362fb086dcc0bd4413df2b5b60c598680120e8e4c2adc7358564e453d7293fb970b4e35feb93e09

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.10.0"
+  VERSION = "0.12.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
@@ -337,6 +337,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")
@@ -355,10 +359,11 @@ module Mailkite
     end
 
     # --- Messages & deliveries -----------------------------------------
-    def listMessages(before = nil, limit = nil)
+    def listMessages(before = nil, limit = nil, search = nil)
       params = []
       params << "before=#{CGI.escape(before.to_s)}" unless before.nil?
       params << "limit=#{CGI.escape(limit.to_s)}" unless limit.nil?
+      params << "search=#{CGI.escape(search.to_s)}" unless search.nil?
       path = "/api/messages"
       path += "?#{params.join('&')}" unless params.empty?
       request("GET", path)
@@ -475,3 +480,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.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - MailKite
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-28 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