Upgrade guide

Upgrade from 1.x to 2.0

1.x no longer receives updates, including fixes. Upgrade to 2.0 to keep getting them.

2.0 is a new major version. It moves the Elixir SDK onto the same design as the other Lettermint SDKs: one client for both tokens, the Team API grouped by resource with the same function names in every language, typed errors for every outcome, and types generated from the current API specification. The 1.x strengths stay: clients and builders are immutable, the builder works with the pipe operator, the idempotency key is a per-call option, redirects and retries are off, and decoding never creates atoms.

Highlights

• One client: Lettermint.new(sending_token: ..., team_token: ...), or Lettermint.new(token). It replaces Lettermint.email(token, opts) and Lettermint.api(token, opts).
• Each part uses its own token: Lettermint.Emails uses the sending token, the Team API the team token. The SDK never falls back to the other token; a missing token raises Lettermint.ConfigError that names the option.
• The Team API uses the layout of the other SDKs: Lettermint.Projects.ReportForwarding, Lettermint.Team.Members and Lettermint.Webhooks.Deliveries are their own modules, and every list has an iterate function that returns a Stream.
• Query parameters are nested maps (%{page: %{size: 30}}) instead of bracketed string keys.
• Errors are exception structs per kind (Lettermint.NotFoundError, Lettermint.RateLimitError, Lettermint.TimeoutError, …) instead of one %Lettermint.Error{kind: ...}. Network errors keep their reason (1.x reported only :connection_failed).
• The timeout covers the whole request, including the body.
• An empty 2xx body where JSON is expected is an error (1.x returned {:ok, nil}). A request body that cannot be encoded as JSON is an error (1.x raised Jason.EncodeError).
• Webhook verification takes the request headers, requires the X-Lettermint-Delivery header and returns the decoded payload.
• Tokens are kept inside closures, so they no longer show up in inspect(client, structs: false), :io_lib.format("~p", ...) or crash reports.
• Types are generated from the current API specification and use its names, under Lettermint.Types (see Type names).
• Requires Erlang/OTP 25 or later (for :crypto.hash_equals/2). Elixir 1.15+ as before.

Requirements

• Elixir 1.15 or later.
• Erlang/OTP 25 or later.

Upgrade with a coding agent

You can let a coding agent (Claude Code, Codex, Cursor, Copilot, …) do the upgrade. Copy this instruction into the agent from your project's root, then review its changes:

Upgrade this project from the `lettermint` Elixir SDK 1.x to 2.0.

1. Change the dependency in mix.exs to `{:lettermint, "~> 2.0"}` and run `mix deps.update lettermint`. 2.0 needs Elixir 1.15+ and Erlang/OTP 25+: check `.tool-versions`, `mix.exs`, CI workflows and Dockerfiles, and report anything older.
2. Read the upgrade guide before changing code: `deps/lettermint/UPGRADE.md`, or https://github.com/lettermint/lettermint-elixir/blob/main/UPGRADE.md. Treat it as the source of truth and don't guess APIs; when unsure, read the source in `deps/lettermint/lib/` or the docs on HexDocs.
3. Find every use of the SDK: `Lettermint.email(`, `Lettermint.api(`, `Lettermint.Email.`, `Lettermint.API.`, `Lettermint.EmailBuilder`, `Lettermint.MessageTag`, `Lettermint.Model.`, `Lettermint.Models.`, `%Lettermint.Error{`, `Lettermint.Webhook.verify(`, the 1.x Team API modules (`Lettermint.Domains`, `Lettermint.Messages`, `Lettermint.Projects`, `Lettermint.Routes`, `Lettermint.Stats`, `Lettermint.Suppressions`, `Lettermint.Team`, `Lettermint.Webhooks`), `query:` and `headers:` request options, `Lettermint.Adapter` implementations, and the 1.x type names from the guide's type-name table.
4. Rewrite each use following the guide's before/after examples:
   - Create one client with `Lettermint.new(sending_token: ...)`, adding `team_token:` only where the Team API is used. Keep the project's existing environment variable names and config.
   - Keep the builder pipelines, but start them with `Lettermint.Emails.compose(client)` instead of `EmailBuilder.new(client)`. Replace `attachments/2` with `attach/2` and `to_map/1` with `build/1`.
   - Keep idempotency keys as the `idempotency_key:` option of `send`/`send_batch`.
   - Team API: pass query parameters as nested maps in the argument before the options (`Lettermint.Domains.list(client, %{page: %{size: 10}})`), not as `query:` with bracketed keys, and use the renamed functions from the guide.
   - Errors: match on the 2.0 exception structs (`%Lettermint.NotFoundError{}`, `%Lettermint.ValidationError{}`, …) or use the guards in `Lettermint.Error`, instead of `%Lettermint.Error{kind: ...}`.
   - Webhooks: `Lettermint.Webhook.new(secret) |> Lettermint.Webhook.verify(raw_body, conn.req_headers)`. Keep passing the raw request body, keep the secret's `whsec_` prefix, and make sure the `X-Lettermint-Signature` and `X-Lettermint-Delivery` headers reach the handler.
   - Rename `Lettermint.Models.*` types to `Lettermint.Types.*` using the guide's type-name table, and `Lettermint.Model.to_map/from_map` to `Lettermint.Types.to_map/decode`.
5. Run `mix format`, `mix compile --warnings-as-errors` and `mix test`, and fix every error. Don't send real email or call the live API while testing.
6. Finish with a summary: the files you changed, anything you could not migrate with certainty, and behaviour changes I should review.

Never print, log or commit API tokens or webhook secrets.

Create the client

Lettermint.email(token, opts) and Lettermint.api(token, opts) are removed. One client holds both tokens.

# 1.x
email = Lettermint.email(System.fetch_env!("LETTERMINT_PROJECT_TOKEN"), timeout: 10_000)
api = Lettermint.api(System.fetch_env!("LETTERMINT_TEAM_TOKEN"))

# 2.0
lettermint =
  Lettermint.new(
    sending_token: System.get_env("LETTERMINT_PROJECT_TOKEN"), # for Lettermint.Emails
    team_token: System.get_env("LETTERMINT_TEAM_TOKEN"),       # for the Team API
    timeout: 10_000
  )

Pass one token or both. With only one token, calling a function that needs the other raises Lettermint.ConfigError (for example domains.list needs :team_token) before any request. 1.x raised ArgumentError ("Wrong client for this API operation").

You can also pass a token string. The SDK chooses the token type by its format:

Lettermint.new("lm_team_...")                    # team token
Lettermint.new("lm_...")                         # project sending token
Lettermint.new(token, timeout: 10_000)           # with options

Any other format (SSO tokens, an empty string) raises Lettermint.ConfigError. Use sending_token: or team_token: for those.

The :base_url, :timeout and :adapter options work as before, with these changes:

• Invalid options raise Lettermint.ConfigError instead of ArgumentError.
• :timeout now covers the whole request. In 1.x it applied separately to connecting and to receiving.
• :adapter may be {module, options}. The Lettermint.Adapter callback changed; see Adapters.

Send an email

# 1.x
client = Lettermint.email(token)

client
|> Lettermint.EmailBuilder.new()
|> Lettermint.EmailBuilder.from("Acme <hello@acme.com>")
|> Lettermint.EmailBuilder.to(["jane@example.com"])
|> Lettermint.EmailBuilder.subject("Welcome")
|> Lettermint.EmailBuilder.html("<p>Hi Jane</p>")
|> Lettermint.EmailBuilder.send(idempotency_key: "welcome-jane")

Lettermint.Email.send(client, %{from: "Acme <hello@acme.com>", to: ["jane@example.com"], subject: "Welcome"})

# 2.0
alias Lettermint.EmailBuilder, as: Email

lettermint
|> Lettermint.Emails.compose()
|> Email.from("Acme <hello@acme.com>")
|> Email.to("jane@example.com")
|> Email.subject("Welcome")
|> Email.html("<p>Hi Jane</p>")
|> Email.send(idempotency_key: "welcome-jane")

Lettermint.Emails.send(lettermint, %{from: "Acme <hello@acme.com>", to: ["jane@example.com"], subject: "Welcome"})

Changed builder functions

Unchanged: from/2, subject/2, text/2, route/2, headers/2, metadata/2, settings/2, tag/2, tags/2. Every function still returns a new builder.

inspect(builder) now shows the message (#Lettermint.EmailBuilder<%{"from" => ...}>) and never the client's tokens. 1.x showed nothing.

Plain messages

Lettermint.Email.send/3 is now Lettermint.Emails.send/3. Messages are still maps in the API's field names with atom or string keys, or a struct (%Lettermint.Types.SendMailRequest{}, was %Lettermint.Models.SendMailRequest{}). Changes:

• Invalid tags or attachments return {:error, %Lettermint.ClientValidationError{}} before any request. 1.x sent them to the API.
• A body that cannot be encoded as JSON (invalid UTF-8, a PID, a tuple) returns {:error, %Lettermint.ClientValidationError{field: "body"}}. 1.x raised.
• Attachment content is base64 text as before, or {:bytes, binary}, which the SDK encodes.
• Lettermint.MessageTag.new!/2 is removed. Pass %{name: ..., value: ...} maps or %Lettermint.Types.MessageTagInput{} structs; the SDK validates them on send.

Batch sending and ping

# 1.x
Lettermint.Email.send_batch(client, [message1, message2], idempotency_key: "batch-1")
Lettermint.Email.ping(client)
Lettermint.API.ping(api)

# 2.0
Lettermint.Emails.send_batch(lettermint, [message1, message2], idempotency_key: "batch-1")
Lettermint.Emails.send_batch(lettermint, [builder1, builder2]) # builders work too
Lettermint.Emails.ping(lettermint) # sending token
Lettermint.ping(lettermint)        # team token if configured, otherwise the sending token

send_batch/3 returns {:ok, [%Lettermint.Types.SendMailResponse{}]} (was [%Lettermint.Models.SendBatchEmailResponseItem{}]).

Team API

The modules keep their names, but take the one client, and the nested resources have their own modules. Query parameters move from the query: option to an argument before the options, as nested maps. Every list also has an iterate function that returns a Stream.

# 1.x
api = Lettermint.api(token)
{:ok, page} = Lettermint.Domains.list(api, query: %{"page[size]" => 10, "filter[status]" => "verified"})

# 2.0
{:ok, page} = Lettermint.Domains.list(lettermint, %{page: %{size: 10}, filter: %{status: "verified"}})

lettermint
|> Lettermint.Domains.iterate(%{filter: %{status: "verified"}})
|> Enum.each(&IO.puts(&1.domain))

Lettermint.Messages.reschedule/4 and cancel/3 accept either token: the team token when configured, otherwise the sending token. This lets a sending-only client cancel the scheduled email it sent.

Request options

Every function takes a keyword list of options last.

Unknown options raise Lettermint.ConfigError (1.x: ArgumentError).

Query parameters

Write bracketed names as nested maps (atom or string keys). Lists of values are joined with commas, lists of maps are indexed, and booleans are sent as 1/0.

Path parameters

IDs are still URL-encoded. An empty ID, "." or ".." raises Lettermint.ConfigError before the request, as in 1.x (which raised ArgumentError).

Lists and pagination

List responses decode into %Lettermint.Types.CursorPage{data: [...], next_cursor: ..., ...} (1.x had one struct per list, such as %Lettermint.Models.DomainIndexResponse{}, with the same fields). Read page.next_cursor, or use iterate, which follows it for you and stops on a repeated cursor. A stream raises the error of a failed page, because a stream cannot return {:error, error}.

Errors

%Lettermint.Error{kind: ..., status: ..., body: ...} is replaced by one exception struct per kind. Lettermint.Error is now a module with guards (is_lettermint_error/1, is_api_error/1).

code comes from {"error": {"code": ...}} or a string error field. message is the API's message, or "HTTP <status>". Every error is an exception, so you can also raise error.

# 1.x
case Lettermint.Email.send(client, message) do
  {:ok, result} -> result
  {:error, %Lettermint.Error{kind: :api, status: 422, body: body}} -> {:invalid, body}
  {:error, %Lettermint.Error{kind: :api, status: 429}} -> :retry_later
  {:error, %Lettermint.Error{kind: kind}} -> {:failed, kind}
end

# 2.0
case Lettermint.Emails.send(lettermint, message) do
  {:ok, result} -> result
  {:error, %Lettermint.ValidationError{errors: errors}} -> {:invalid, errors}
  {:error, %Lettermint.RateLimitError{retry_after: seconds}} -> {:retry_later, seconds}
  {:error, error} -> {:failed, error}
end

The SDK does not retry requests. Pass an idempotency_key when you retry a send.

Webhooks

# 1.x
:ok = Lettermint.Webhook.verify(raw_body, signature_header, secret, tolerance: 300)

# 2.0
webhook = Lettermint.Webhook.new(secret, tolerance: 300)
{:ok, payload} = Lettermint.Webhook.verify(webhook, raw_body, conn.req_headers)
{:ok, payload} = Lettermint.Webhook.verify_signature(webhook, raw_body, signature_header, timestamp: delivery_header)

• The secret moves into a verifier struct, Lettermint.Webhook.new/2. An empty secret or a negative tolerance raises Lettermint.ConfigError (1.x returned {:error, :invalid_signature}).
• verify/4 takes the request headers (a map, a list such as conn.req_headers, or a Plug.Conn) and requires both X-Lettermint-Signature and X-Lettermint-Delivery, which must equal the signed timestamp. 1.x did not read the delivery header.
• On success it returns {:ok, %Lettermint.WebhookPayload{id, event, timestamp, data, extra}} (1.x: :ok), so you no longer decode the body yourself.
• Failures return {:error, %Lettermint.WebhookVerificationError{reason: reason}} instead of {:error, :invalid_signature}. The reasons are :signature_header_missing, :signature_header_malformed, :delivery_header_missing, :delivery_timestamp_mismatch, :timestamp_out_of_tolerance, :signature_mismatch, :body_invalid and :payload_invalid.
• The :now option (Unix seconds) works as before, on verify/4 and verify_signature/4. :tolerance moves to new/2.

Adapters

The Lettermint.Adapter behaviour changed so that the SDK can read response headers (Retry-After, Content-Type):

The SDK runs the adapter in a task and enforces the timeout itself. {:error, reason} becomes Lettermint.ConnectionError with that reason (:timeout becomes Lettermint.TimeoutError).

Type names

The types are generated from the API specification of lettermint#2582 and use its names. They move from Lettermint.Models to Lettermint.Types. Lettermint.Model.to_map/1 is now Lettermint.Types.to_map/1, and Lettermint.Model.from_map/2 is Lettermint.Types.decode/2. Some shapes also changed:

• Enums are open, as before: unknown values decode as strings, and enum modules keep values/0.
• SendMailResponse (was SendEmailResponse and SendBatchEmailResponseItem) holds the fields of a pending and of a scheduled send; check status.
• MessageTag describes tags in responses; MessageTagInput describes tags you send (was SendMailRequestTagsItem).
• Every list is Lettermint.Types.CursorPage (see Lists and pagination). The per-list modules, such as ListDomainsResponse, are typespecs for CursorPage.t(item).
• Query parameters have typespec modules, such as Lettermint.Types.ListDomainsQuery.

• Typespecs now tell required fields (T), optional fields (T | :unset) and nullable fields (T | nil) apart. 1.x typed every field as T | nil | :unset.

These types keep their name and only move from Lettermint.Models to Lettermint.Types:

AttachmentDelivery, BuiltInTeamRole, DeliveryMode, DkimMode, DnsRecordPurpose, DnsRecordStatus, DnsVerificationScope, DomainData, DomainDataProjectsItem, DomainDnsRecordData, DomainListData, DomainStatus, GetReportForwardingResponse, InitialRoutes, MessageAttachmentData, MessageData, MessageEventData, MessageEventType, MessageListData, MessageRecipientData, MessageStatsData, MessageStatus, MessageType, Plan, ProcessInboundMessageResponse, ProjectAccessScope, ProjectCreatedData, ProjectData, ProjectListData, RbacConflictCode, RbacPermission, RecordType, ReportForwardingRequest, ReportForwardingResource, RescheduleMessageRequest, ResendReportForwardingCodeResponse, RouteData, RouteDataSettings, RouteListData, RouteStatisticData, RouteType, SandboxResult, SendMailRequest, SendMailRequestSettings, SpamSymbol, StatsDailyData, StatsData, StatsInboundData, StatsTotalsData, StatsTypeData, StoreDomainData, StoreProjectData, StoreRouteData, StoreSuppressionData, StoreWebhookData, SuppressedRecipientData, SuppressionAppliesTo, SuppressionReason, SuppressionScope, SuppressionSourceMessageData, SuppressionStoreResponse, SuppressionType, TeamAddonData, TeamData, TeamMemberData, TeamMemberDataRole, TeamMemberProjectAccessData, TeamMemberProjectAccessDataProjectsItem, TeamRoleData, TeamType, TeamUsageDetailData, TeamUsagePeriodData, TlsPolicy, UpdateDomainProjectsData, UpdateProjectData, UpdateReportForwardingResponse, UpdateRouteData, UpdateRouteInboundSettingsData, UpdateRouteSettingsData, UpdateTeamData, UpdateTeamMemberAssignmentData, UpdateTeamMemberAssignmentDataProjectAccess, UpdateWebhookData, VerifyReportForwardingRequest, VerifyReportForwardingResponse, WebhookBasicAuthData, WebhookData, WebhookDeliveryData, WebhookDeliveryListData, WebhookDeliveryModeFilter, WebhookDeliveryStatus, WebhookEvent, WebhookListData, WebhookScope, WebhookSecretData

These types are renamed:

Removed types

lettermint#2582 removed these schemas from the API specification. 1.x exported all five:

Removed modules and functions