mailgazelle 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3db3d2ef7db7297af73576fb689bec36b50040164b1a9aee85285940afa53ed
+  data.tar.gz: 9edad81d53947dc2ed0a3356ed5e018ccce2bf5dc792747644f74b616efde0aa
+SHA512:
+  metadata.gz: 85f5da70c808884739954a9b9bea04844db89c967dd205490d1b96671ce9f4d6b49999b2dedb454256ebfba4960464079576ca05a66a639e67ac9501df062379
+  data.tar.gz: e9673cadefc6f9014e34bc023fed5dd957d22b438ca2f1ad1d006204a080af83814059cc7dce45a5410e852fdd927ce6195a0821931e01aa05d8dbb743cf1d94

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 1.0.0
+
+- Send and fetch transactional email, and list product domains, through the Mail Gazelle API.
+- Deliver Rails mail with ActionMailer's `:mailgazelle` delivery method.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mailgazelle
+
+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,265 @@
+# Mail Gazelle Ruby and Rails SDK
+
+Official Ruby client for the [Mail Gazelle](https://mailgazelle.com) transactional email API, with an ActionMailer delivery method for Rails.
+
+A gem is a packaged Ruby library. Add this one to an application and that application can send mail through Mail Gazelle without talking to the HTTP API itself.
+
+The HTTP contract lives in [docs/api.md](docs/api.md). Keep that file and this gem in the same change when endpoints, error codes, or attachment limits change.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- A Mail Gazelle API token for a product that is ready to send (`tes_…`)
+
+There are no runtime gem dependencies. Rails is not required. The ActionMailer delivery method loads only when the host application has already loaded Rails.
+
+## Install
+
+Add the gem to the application's `Gemfile`:
+
+```ruby
+gem "mailgazelle"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+Or install it for the whole machine, outside an application:
+
+```bash
+gem install mailgazelle
+```
+
+## Create a client
+
+```ruby
+require "mailgazelle"
+
+client = MailGazelle::Client.new(api_token: ENV.fetch("MAILGAZELLE_API_TOKEN"))
+```
+
+The default API root is `https://mailgazelle.com/api/v1`. Tokens are minted in the Mail Gazelle admin UI for a product that is ready to send. The raw token is shown once.
+
+Reuse one client per token. Do not construct a new client for every send.
+
+| Argument | Default | Purpose |
+|---|---|---|
+| `api_token` | none | Bearer token (`tes_…`). Required. |
+| `base_url` | `https://mailgazelle.com/api/v1` | Override the API root. A trailing slash is ignored. |
+| `transport` | `Net::HTTP` | Inject an object that implements `perform` and returns a response. Useful in tests. |
+| `timeout` | `30` seconds | Read and write timeout. |
+| `connect_timeout` | `10` seconds | Connection timeout. |
+| `user_agent_suffix` | none | Appended to `mailgazelle-ruby/{version}`. |
+
+```ruby
+client = MailGazelle::Client.new(
+  api_token: ENV.fetch("MAILGAZELLE_API_TOKEN"),
+  user_agent_suffix: "MyApp/2.4"
+)
+```
+
+You can also set process-wide defaults. `MailGazelle.client` builds one client from them and raises `MailGazelle::ApiTokenMissing` if the token is blank:
+
+```ruby
+MailGazelle.configure do |config|
+  config.api_token = ENV.fetch("MAILGAZELLE_API_TOKEN")
+end
+```
+
+## Send email
+
+Either HTML or plain text is required. Both may be sent together. `to` is one or more recipients. Together with `cc` and `bcc`, a message can include at most 50 addresses.
+
+### Plain text
+
+```ruby
+queued = client.emails.send(
+  MailGazelle::Email.to("user@example.com", "Ada")
+    .subject("Welcome")
+    .text("Thanks for signing up.")
+)
+
+queued.id      # Mail Gazelle message id
+queued.status  # "queued"
+```
+
+`POST /emails` returns `202` immediately. The message is stored and queued. Delivery happens asynchronously.
+
+### HTML, recipients, and attachments
+
+```ruby
+client.emails.send(
+  MailGazelle::Email.to("user@example.com", "Ada")
+    .add_to("other@example.com")
+    .cc("billing@example.com")
+    .bcc("audit@example.com")
+    .subject("Invoice")
+    .html("<p>Your invoice is attached.</p><img src=\"cid:logo\">")
+    .text("Your invoice is attached.")
+    .from("notif@example.com", "App")
+    .reply_to("support@example.com")
+    .header("Message-ID", "<invoice-42@example.com>")
+    .tag("campaign", "welcome")
+    .idempotency_key("invoice-42")
+    .attach(MailGazelle::Attachment.from_path("/tmp/invoice.pdf"))
+    .attach(MailGazelle::Attachment.from_contents("logo.png", png_bytes, content_id: "logo"))
+)
+```
+
+`from` and `reply_to` are omitted when you do not set them, so the product defaults apply. A custom From address must use the product's primary or sending domain. `without_reply_to` sends `"reply_to": []`, which removes Reply-To. `bcc` is stored and delivered, and omitted from the visible MIME headers.
+
+An idempotency key is unique per team. The same key returns the original message and does not send again. A replay is not checked against quota. The SDK does not retry failed requests. Set an idempotency key when a caller may repeat a send.
+
+HTML must be 512 KB or smaller. The SDK checks that before it calls the API.
+
+### Attachments
+
+`Attachment.from_path` reads a file. `from_contents` takes raw bytes. `from_base64` takes content that is already base64-encoded.
+
+Filenames must be a basename. Path segments are rejected. `content_type` is guessed from the filename when omitted. `content_id` marks an inline part. Reference it from HTML as `cid:{content_id}`. A leading `cid:` and surrounding angle brackets are stripped. Empty or duplicate ids are rejected.
+
+The SDK enforces the 7 MB decoded platform ceiling. How many files a plan allows, and any lower size limit, are enforced by the API. The assembled raw MIME must be 10 MB or smaller (`message_too_large`).
+
+### Fetch a message
+
+`GET /emails/{id}` returns status, timestamps, the provider message id, the last event type, and attachment metadata. It does not return HTML, text, or file bytes.
+
+```ruby
+record = client.emails.get(queued.id)
+
+record.status           # for example "queued" or "rejected"
+record.known_status     # "queued" or "rejected" when this gem knows the value, otherwise nil
+record.message_id       # provider id after accept, or nil
+record.last_event_type
+record.created_at
+record.attachments      # filename, content type, size
+record.to_h             # full payload, including fields added later
+```
+
+### List domains
+
+```ruby
+client.domains.list.each do |domain|
+  domain.name
+  domain.type
+  domain.verification_statuses
+  domain.to_h
+end
+```
+
+## Rails
+
+Add the gem to the Gemfile, then select the delivery method. Mailers stay normal ActionMailer classes. `deliver_now` and `deliver_now!` perform the HTTP call.
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :mailgazelle
+config.action_mailer.mailgazelle_settings = {
+  api_token: ENV.fetch("MAILGAZELLE_API_TOKEN")
+  # api_base: ENV["MAILGAZELLE_BASE_URL"] # optional
+}
+```
+
+`api_base`, `base_url`, `timeout`, and `connect_timeout` are optional. A token in `MailGazelle.configure` is used when the delivery settings do not include one. A missing token raises `MailGazelle::ApiTokenMissing` on the first send.
+
+```ruby
+# app/mailers/user_mailer.rb
+class UserMailer < ApplicationMailer
+  def welcome
+    mail(
+      to: "Ada <ada@example.com>",
+      subject: "Welcome",
+      tags: { campaign: "welcome" },
+      "MailGazelle-Idempotency-Key" => "welcome-42"
+    )
+  end
+end
+```
+
+```ruby
+UserMailer.welcome.deliver_now!
+```
+
+`MAIL_FROM` / `default from:` on the mailer is sent as `from` when present. Omit it to keep the product From. Reply-To on the message is sent as `reply_to`. Inline attachments (`attachments.inline`) include a content id.
+
+`tags:` becomes the tags object. Names and values must match `[A-Za-z0-9_-]`. `team_id` and `product_id` are reserved.
+
+`MailGazelle-Idempotency-Key` is not sent as a header. It becomes `idempotency_key`.
+
+Custom headers are forwarded, except `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Sender`, `Subject`, `Content-Type`, `Content-Transfer-Encoding`, `Return-Path`, `MIME-Version`, and `Date`. `Message-ID` is forwarded.
+
+`deliver_now!` returns the queued result because the delivery method asks Mail for the response. The Mail Gazelle id is also stored on the message as `X-MailGazelle-Message-Id`, and as the message id.
+
+```ruby
+message = UserMailer.welcome.deliver_now!
+message.id # Mail Gazelle message id
+```
+
+## Errors
+
+All failures subclass `MailGazelle::Error`. Catch that type when you only need to know that a call failed. Use a subclass when the recovery path depends on the cause.
+
+```ruby
+begin
+  client.emails.send(email)
+rescue MailGazelle::RecipientSuppressedError
+  # Stored as rejected. Do not retry this address.
+rescue MailGazelle::RateLimitError
+  # 60 requests per minute per token. Back off and retry later.
+rescue MailGazelle::Error => error
+  error.message
+  error.code         # API error code
+  error.http_status  # 0 when no HTTP response was received
+  error.details
+end
+```
+
+The SDK validates documented limits before it calls the API. Local and remote failures of the same kind raise the same class. Plan-specific limits that are lower than the platform ceiling are left to the API.
+
+| API `code` | Error class | Typical HTTP |
+|---|---|---|
+| `unauthenticated` | `AuthenticationError` | 401 |
+| `product_not_ready` | `ProductNotReadyError` | 403 |
+| `validation_error` | `ValidationError` | 422 |
+| `from_not_allowed` | `FromNotAllowedError` | 422 |
+| `recipient_suppressed` | `RecipientSuppressedError` | 422 |
+| `attachment_invalid` | `AttachmentError` | 422 |
+| `attachment_too_large` | `AttachmentTooLargeError` | 422 |
+| `quota_exceeded` | `QuotaExceededError` | 422 |
+| `html_too_large` | `HtmlTooLargeError` | 422 |
+| `message_too_large` | `MessageTooLargeError` | 422 |
+| `rate_limited` | `RateLimitError` | 429 |
+
+`unauthenticated` also covers a token for an archived product. `recipient_suppressed` does not consume quota. `quota_exceeded` means the send would pass the team's monthly email allowance, daily send limit, or monthly attachment allowance. The message says which limit was hit.
+
+Unknown codes become `ApiError`. Network, DNS, TLS, and timeout failures become `TransportError`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+Tests stub HTTP. They do not call Mail Gazelle.
+
+## Release
+
+The published gem is [mailgazelle on RubyGems](https://rubygems.org/gems/mailgazelle). Shipping a version is a separate step from installing it.
+
+1. Sign in at [rubygems.org](https://rubygems.org/sign_up) with the account that should own the gem, and turn on multi-factor authentication. This gemspec requires MFA for every push.
+2. Create an API key at [rubygems.org/profile/api_keys](https://rubygems.org/profile/api_keys) with the **Push rubygem** scope. RubyGems shows the key once.
+3. From this repository, with a clean git tree and the version you want in `lib/mailgazelle/version.rb`:
+
+```bash
+gem build mailgazelle.gemspec
+gem push mailgazelle-1.0.0.gem
+```
+
+`gem push` asks for the API key the first time and stores it in `~/.gem/credentials`. The first successful push reserves the name `mailgazelle` for that account. A version that has been pushed cannot be uploaded again, including after a yank.
+
+`bundle exec rake release` does the same push, and also creates a git tag and pushes it. Use that only after the commit you are releasing is already on `main`.

data/docs/api.md

@@ -0,0 +1,183 @@
+# Mail Gazelle public API
+
+Client integration contract for sending transactional email through Mail Gazelle. Update this file in the same change as any public API, auth, error-code, or attachment-limit change.
+
+Operator environment names live in `.env.example`. Do not put AWS keys or raw tokens in this file.
+
+## Base URL and auth
+
+- Base URL: `{APP_URL}/api/v1`
+- Authenticate with `Authorization: Bearer tes_…`
+- Tokens are minted on a **ready** product (sending DKIM verified and MAIL FROM success). The raw token is shown once in the admin UI.
+- Rate limit: 60 requests per minute per token.
+- A disabled or paused team, or a product that is not `ready`, cannot send (`403`, `product_not_ready`).
+- An archived product is treated as gone: its tokens return `401` `unauthenticated` (same as an invalid token).
+
+## Onboarding
+
+1. Create a product with a name and primary domain. Sending identity and MAIL FROM default to `notif.{primary}` and `bounce.notif.{primary}`; both can be edited on create.
+2. Add the DNS records from the product checklist for that sending identity and MAIL FROM.
+3. Click **Check now** (or wait for the minute poll). The product becomes `ready` only when sending DKIM and MAIL FROM are both success.
+4. Create an API token.
+
+The apex domain is not created as an SES identity on the default path. DMARC is recommended, not a ready-gate.
+
+## Endpoints
+
+### `POST /emails`
+
+Persists the message, stores attachments on disk, and queues a send. Returns `202` immediately. SES is not called in the request.
+
+```json
+{
+  "id": "01J…",
+  "status": "queued"
+}
+```
+
+JSON body:
+
+| Field | Required | Notes |
+|---|---|---|
+| `to` | yes | One or more `{ "email", "name?" }`. Together with `cc` and `bcc`, at most 50 addresses |
+| `cc` | no | Same shape as `to` |
+| `bcc` | no | Same shape as `to`. Stored and delivered, omitted from the visible MIME headers |
+| `subject` | yes | |
+| `html` or `text` | one required | HTML ≤ 512 KB. Both may be sent together |
+| `from` | no | Defaults to the product From. Domain must be that product's `primary` or `sending` host |
+| `reply_to` | no | Defaults to the product Reply-To. Send `[]` to omit Reply-To |
+| `headers` | no | Object of header name to string. `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Sender`, `Subject`, `Content-Type`, and `Return-Path` are ignored. `Message-ID` is kept when it is present |
+| `tags` | no | Object of names and values, each matching `[A-Za-z0-9_-]`, name ≤ 64 characters, value ≤ 256. At most 48. Invalid tags are `validation_error` (they are not dropped). `team_id` and `product_id` are reserved |
+| `idempotency_key` | no | Unique per team. Same key returns the original message and does not send again. A replay is not checked against the monthly quota |
+| `attachments` | no | See below |
+
+### `GET /emails/{id}`
+
+Returns status, timestamps, SES message id, last event type, and attachment metadata (filename, content type, size). Does not return HTML, text, or file bytes.
+
+### `GET /domains`
+
+Lists the token's product domains and verification statuses.
+
+## Attachments
+
+Optional JSON array, same shape as Resend/Postmark:
+
+```json
+"attachments": [
+  {
+    "filename": "invoice.pdf",
+    "content": "<base64>",
+    "content_type": "application/pdf",
+    "content_id": null
+  }
+]
+```
+
+- `filename` and `content` are required.
+- `content_type` is optional (guessed from the filename).
+- `content_id` is optional. When set, the part is inline (`multipart/related`). Reference it from HTML as `cid:{content_id}`. Angle brackets and a leading `cid:` are stripped. Empty or duplicate ids on one message are `attachment_invalid`.
+- Filename must be a basename — path segments are rejected (`attachment_invalid`).
+- The attachment count and decoded total per message are set by the team's plan. Defaults are 10 attachments and 7 MB. More attachments than allowed is `validation_error`. A larger decoded total is `attachment_too_large`, and `message` states the team's size limit. 7 MB is the platform ceiling on every plan.
+- Empty or invalid base64 is `attachment_invalid`.
+- A team may also have a monthly decoded-byte allowance. Crossing it is `quota_exceeded` (below), which is separate from this per-message limit.
+- The assembled raw MIME (HTML, text, headers, and base64 attachments) must be 10 MB or smaller. A larger message is `message_too_large` and is not queued.
+
+SES Simple cannot carry attachments. Mail Gazelle always sends `Content.Raw`.
+
+## Suppressions
+
+The send path checks the **team** (account) and global suppression lists against every `to`, `cc`, and `bcc` address. A suppressed recipient is stored as a `rejected` message (no SES send) and returns `422`:
+
+```json
+{ "message": "This recipient is suppressed.", "code": "recipient_suppressed" }
+```
+
+Permanent bounces and complaints write the address to the team list and the SES account suppression list. A suppressed reject does not consume the monthly email or attachment quota.
+
+## Quotas
+
+Each team's plan sets how many emails and how many decoded attachment bytes are included each UTC month, plus an optional daily send limit (UTC day). The platform admin can change these per team, so they are not a single platform-wide limit.
+
+When a new send would pass a limit, the API returns `422` and does not queue the message. `message` says which limit was hit:
+
+```json
+{ "message": "Monthly email quota exceeded.", "code": "quota_exceeded" }
+```
+
+```json
+{ "message": "Daily email limit exceeded.", "code": "quota_exceeded" }
+```
+
+```json
+{ "message": "Monthly attachment quota exceeded.", "code": "quota_exceeded" }
+```
+
+Plans that allow additional sending, or additional attachment size, keep sending after the monthly amount is used. For those plans the monthly checks never return `quota_exceeded`. The daily limit applies to every plan that has one.
+
+Each distinct `to`, `cc`, and `bcc` address on an accepted message counts as one send. The same address listed more than once counts once. Decoded attachment bytes count once per recipient. `recipient_suppressed` rejects are not counted, and their attachment bytes are not counted. Replaying an idempotency key that is already stored returns that message and does not re-check any limit. A send with no attachments is not blocked by the attachment allowance. A request that would pass the remaining monthly, daily, or attachment allowance is rejected whole.
+
+## Errors
+
+All API errors use:
+
+```json
+{ "message": "…", "code": "…", "details": {} }
+```
+
+`details` is optional. Responses never include AWS stack traces, message bodies, or attachment bytes.
+
+| Code | Typical status |
+|---|---|
+| `unauthenticated` | 401 |
+| `product_not_ready` | 403 |
+| `validation_error` | 422 |
+| `from_not_allowed` | 422 |
+| `recipient_suppressed` | 422 |
+| `attachment_invalid` | 422 |
+| `attachment_too_large` | 422 |
+| `quota_exceeded` | 422 |
+| `html_too_large` | 422 |
+| `message_too_large` | 422 |
+| `rate_limited` | 429 |
+
+## Sandbox vs production
+
+Until AWS takes the SES account out of sandbox, you can only send to verified identities. Simulator addresses work in sandbox:
+
+- `success@simulator.amazonses.com`
+- `bounce@simulator.amazonses.com`
+- `complaint@simulator.amazonses.com`
+
+## Examples
+
+Text send:
+
+```bash
+curl -X POST "$APP_URL/api/v1/emails" \
+  -H "Authorization: Bearer tes_…" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": [{"email": "user@example.com"}],
+    "subject": "Welcome",
+    "text": "Thanks for signing up."
+  }'
+```
+
+Send with a PDF:
+
+```bash
+curl -X POST "$APP_URL/api/v1/emails" \
+  -H "Authorization: Bearer tes_…" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": [{"email": "user@example.com"}],
+    "subject": "Invoice",
+    "html": "<p>Your invoice is attached.</p>",
+    "attachments": [{
+      "filename": "invoice.pdf",
+      "content": "'"$PDF_BASE64"'",
+      "content_type": "application/pdf"
+    }]
+  }'
+```

data/lib/mailgazelle/address.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "uri"
+require "mailgazelle/error"
+
+module MailGazelle
+  # An email address with an optional display name.
+  class Address
+    attr_reader :email, :name
+
+    def initialize(email, name = nil)
+      normalized = email.to_s.strip
+      unless URI::MailTo::EMAIL_REGEXP.match?(normalized)
+        raise ValidationError.new(
+          "\"#{email}\" is not a valid email address.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      @email = normalized
+      cleaned = name.to_s.strip
+      @name = cleaned.empty? ? nil : cleaned
+      freeze
+    end
+
+    def to_h
+      payload = { email: email }
+      payload[:name] = name unless name.nil?
+      payload
+    end
+  end
+end

data/lib/mailgazelle/attachment.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "base64"
+require "mailgazelle/error"
+
+module MailGazelle
+  # A file attached to an email, encoded as the API expects.
+  #
+  # Use the named constructors so callers encode bytes only when they already
+  # have base64 content.
+  class Attachment
+    CONTENT_TYPES = {
+      "pdf" => "application/pdf",
+      "png" => "image/png",
+      "jpg" => "image/jpeg",
+      "jpeg" => "image/jpeg",
+      "gif" => "image/gif",
+      "webp" => "image/webp",
+      "svg" => "image/svg+xml",
+      "txt" => "text/plain",
+      "html" => "text/html",
+      "htm" => "text/html",
+      "csv" => "text/csv",
+      "json" => "application/json",
+      "xml" => "application/xml",
+      "zip" => "application/zip",
+      "ics" => "text/calendar",
+      "doc" => "application/msword",
+      "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "xls" => "application/vnd.ms-excel",
+      "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    }.freeze
+
+    attr_reader :filename, :content, :content_type, :content_id, :decoded_size
+
+    def self.from_path(path, filename: nil, content_type: nil, content_id: nil)
+      contents = File.binread(path)
+      from_contents(
+        filename || File.basename(path),
+        contents,
+        content_type: content_type,
+        content_id: content_id
+      )
+    rescue SystemCallError
+      raise AttachmentError.new(
+        "Unable to read attachment from \"#{path}\".",
+        code: "attachment_invalid",
+        http_status: 422
+      )
+    end
+
+    def self.from_contents(filename, contents, content_type: nil, content_id: nil)
+      binary = contents.to_s.b
+      create(
+        filename,
+        Base64.strict_encode64(binary),
+        binary.bytesize,
+        content_type,
+        content_id
+      )
+    end
+
+    def self.from_base64(filename, encoded, content_type: nil, content_id: nil)
+      decoded = strict_decode(encoded)
+      if decoded.nil? || decoded.empty?
+        raise AttachmentError.new(
+          "Attachment \"#{filename}\" is not valid base64.",
+          code: "attachment_invalid",
+          http_status: 422
+        )
+      end
+
+      create(filename, encoded, decoded.bytesize, content_type, content_id)
+    end
+
+    def to_h
+      payload = { filename: filename, content: content }
+      payload[:content_type] = content_type unless content_type.nil?
+      payload[:content_id] = content_id unless content_id.nil?
+      payload
+    end
+
+    def self.create(filename, encoded, decoded_size, content_type, content_id)
+      name = filename.to_s.strip
+      assert_basename(name)
+
+      if decoded_size < 1
+        raise AttachmentError.new(
+          "Attachment \"#{name}\" is empty.",
+          code: "attachment_invalid",
+          http_status: 422
+        )
+      end
+
+      type = content_type.to_s.strip
+      type = guess_content_type(name) if type.empty?
+
+      new(name, encoded, type, normalize_content_id(content_id), decoded_size)
+    end
+    private_class_method :create
+
+    def self.assert_basename(filename)
+      return unless filename.empty? || filename == "." || filename == ".." ||
+                    filename.include?("/") || filename.include?("\\") ||
+                    filename != File.basename(filename)
+
+      raise AttachmentError.new(
+        "Attachment filenames must be a basename without path segments.",
+        code: "attachment_invalid",
+        http_status: 422
+      )
+    end
+    private_class_method :assert_basename
+
+    def self.normalize_content_id(content_id)
+      return nil if content_id.nil?
+
+      value = content_id.to_s.strip
+      return nil if value.empty?
+
+      value = value[4..] if value.downcase.start_with?("cid:")
+      value = value.gsub(/\A[ \t<>]+|[ \t<>]+\z/, "")
+      if value.empty? || value.match?(/\s/)
+        raise AttachmentError.new(
+          "Attachment content ids must not be empty.",
+          code: "attachment_invalid",
+          http_status: 422
+        )
+      end
+
+      value
+    end
+    private_class_method :normalize_content_id
+
+    def self.guess_content_type(filename)
+      extension = File.extname(filename).delete_prefix(".").downcase
+      CONTENT_TYPES.fetch(extension, "application/octet-stream")
+    end
+    private_class_method :guess_content_type
+
+    def self.strict_decode(encoded)
+      Base64.strict_decode64(encoded.to_s)
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :strict_decode
+
+    def initialize(filename, content, content_type, content_id, decoded_size)
+      @filename = filename
+      @content = content
+      @content_type = content_type
+      @content_id = content_id
+      @decoded_size = decoded_size
+      freeze
+    end
+    private_class_method :new
+  end
+end