An immutable email builder for the pipe operator. Start one with
Lettermint.Emails.compose/2.
Every function returns a new builder and leaves the one it was given
unchanged, so a base builder can be kept and reused as a template, also
across processes. to/2, cc/2, bcc/2 and reply_to/2 replace their
list; attach/2 appends.
alias Lettermint.EmailBuilder, as: Email
welcome =
lettermint
|> Lettermint.Emails.compose()
|> Email.from("Acme <hello@acme.com>")
|> Email.subject("Welcome to Acme")
|> Email.tags([%{name: "campaign", value: "welcome"}])
welcome |> Email.to("jane@example.com") |> Email.html("<p>Hi Jane</p>") |> Email.send()
welcome |> Email.to("john@example.com") |> Email.html("<p>Hi John</p>") |> Email.send(idempotency_key: "welcome-john")A setter that gets invalid tags or attachments raises
Lettermint.ClientValidationError; the builder it was given stays valid.
inspect/1 and Jason.encode/1 show the message, never the client's tokens.
Summary
Functions
Adds an attachment: a map or keyword list with :filename, :content, and
optionally :content_type (a MIME type, detected by the API when left out)
and :content_id (for inline images referenced as cid:<content_id>).
content is base64 text or {:bytes, binary} with raw bytes.
Replaces the BCC recipients. Takes one address or a list.
The message in the API's wire format (string keys), with attachment bytes base64-encoded. Contains no credentials.
Replaces the CC recipients. Takes one address or a list.
The sender, for example Acme <hello@acme.com>.
Replaces the custom email headers.
The HTML body. nil removes it.
Replaces the metadata (stored with the message, not added as headers).
Replaces the Reply-To addresses. Takes one address or a list.
The route slug to send through.
The result that a Sandbox project simulates for every recipient, for example "hard_bounced".
Schedules delivery. Strings are passed through (ISO 8601 or English, such
as "tomorrow 9am"); a DateTime is sent as ISO 8601. nil removes it.
Sends a snapshot of this email. The builder is unchanged and can be sent
again. Takes the options of Lettermint.Emails.send/3.
Per-email settings that override the route settings (track_opens, track_clicks, tls).
The subject line.
The legacy single tag. nil removes it.
Replaces the name/value tags: up to 20, or 19 with a legacy tag/2. Takes
maps with name and value (atom or string keys) or
Lettermint.Types.MessageTagInput structs.
The plain-text body. nil removes it.
Replaces the recipients. Takes one address or a list.
Types
@type attachment() :: %{ :filename => String.t(), :content => String.t() | {:bytes, binary()}, optional(:content_type) => String.t(), optional(:content_id) => String.t() }
An attachment: content is base64 text or {:bytes, binary}.
@type t() :: %Lettermint.EmailBuilder{client: Lettermint.Client.t(), message: map()}
Functions
@spec attach(t(), attachment() | keyword()) :: t()
Adds an attachment: a map or keyword list with :filename, :content, and
optionally :content_type (a MIME type, detected by the API when left out)
and :content_id (for inline images referenced as cid:<content_id>).
content is base64 text or {:bytes, binary} with raw bytes.
Email.attach(builder, filename: "invoice.pdf", content: {:bytes, pdf}, content_type: "application/pdf")Replaces the BCC recipients. Takes one address or a list.
The message in the API's wire format (string keys), with attachment bytes base64-encoded. Contains no credentials.
Replaces the CC recipients. Takes one address or a list.
The sender, for example Acme <hello@acme.com>.
Replaces the custom email headers.
The HTML body. nil removes it.
Replaces the metadata (stored with the message, not added as headers).
Replaces the Reply-To addresses. Takes one address or a list.
The route slug to send through.
@spec sandbox_result(t(), Lettermint.Types.SandboxResult.t() | atom()) :: t()
The result that a Sandbox project simulates for every recipient, for example "hard_bounced".
@spec scheduled_at(t(), String.t() | DateTime.t() | nil) :: t()
Schedules delivery. Strings are passed through (ISO 8601 or English, such
as "tomorrow 9am"); a DateTime is sent as ISO 8601. nil removes it.
@spec send(t(), Lettermint.Emails.send_options()) :: {:ok, Lettermint.Types.SendMailResponse.t()} | {:error, Lettermint.Error.t()}
Sends a snapshot of this email. The builder is unchanged and can be sent
again. Takes the options of Lettermint.Emails.send/3.
@spec settings(t(), map() | Lettermint.Types.SendMailRequestSettings.t()) :: t()
Per-email settings that override the route settings (track_opens, track_clicks, tls).
The subject line.
The legacy single tag. nil removes it.
@spec tags(t(), [map() | Lettermint.Types.MessageTagInput.t()]) :: t()
Replaces the name/value tags: up to 20, or 19 with a legacy tag/2. Takes
maps with name and value (atom or string keys) or
Lettermint.Types.MessageTagInput structs.
The plain-text body. nil removes it.
Replaces the recipients. Takes one address or a list.