Lettermint
Lettermint Sending API
Lettermint Sending API

Schemas

Download schema

ApiError

Structured API error.
​object · required

ErrorMessage

Error with only a message.
message
​string · required

Error overview.

MessageAttachmentInput

A file attached to the message.
filename
​string · required
content
​string · required
content_type
​string | null · maxLength: 255

The MIME type of the attachment. Supports parameters (e.g. text/calendar; method=REQUEST). If omitted, detected automatically from content or filename.

Example: application/pdf
content_id
​string | null · maxLength: 255 · pattern: ^[a-zA-Z0-9._@-]+$

Content ID for inline attachments, referenced via cid: in HTML body. If no @ is present, @lm is appended automatically.

Example: logo-image

MessageTagInput

A reusable exact-match tag with a name and a value.
name
​string · minLength: 1 · maxLength: 32 · pattern: ^[A-Za-z0-9_-]{1,32}… · required
value
​string · minLength: 1 · maxLength: 64 · pattern: ^[A-Za-z0-9_-]{1,64}… · required

PendingSendMailResponse

An accepted message that is queued for delivery.
message_id
​string · required
status
​string · const · required
Const value: pending
sandbox
​boolean · const

Present when the project uses Sandbox delivery

Const value:
sandbox_result
​SandboxResult · enum

The simulated delivery result. Present when the project uses Sandbox delivery

Enum values:
delivered
hard_bounced
soft_bounced
deferred
failed
suppressed
spam_complaint
auto_replied

SandboxResult

string · enum
Enum values:
delivered
hard_bounced
soft_bounced
deferred
failed
suppressed
spam_complaint
auto_replied

ScheduledSendMailResponse

An accepted message that is scheduled for later delivery.
message_id
​string · required
status
​string · const · required
Const value: scheduled
scheduled_at
​string · required

The scheduled delivery time in ISO 8601 format

sandbox
​boolean · const

Present when the project uses Sandbox delivery

Const value:
sandbox_result
​SandboxResult · enum

The simulated delivery result. Present when the project uses Sandbox delivery

Enum values:
delivered
hard_bounced
soft_bounced
deferred
failed
suppressed
spam_complaint
auto_replied

SendBatchMailItem

from
​string · required
to
​string[] · minItems: 1 · required
subject
​string · maxLength: 998 · required
route
​string
cc
​string[]
bcc
​string[]
reply_to
​string[]
scheduled_at
​string · maxLength: 255

ISO 8601 or English delivery time. A time without a timezone uses UTC.

Example: tomorrow at 9am
sandbox_result
​SandboxResult · enum

The result that a Sandbox project simulates for every recipient.

Enum values:
delivered
hard_bounced
soft_bounced
deferred
failed
suppressed
spam_complaint
auto_replied
Example: hard_bounced
​object

Custom headers to include in the email. To preserve a submitted RFC Message-ID, include both Message-ID and X-LM-Preserve-Message-ID with a string value of true or 1. Header names and control values are case-insensitive; false or 0 retains replacement. Send values as plain text: Lettermint encodes non-ASCII characters and repairs small formatting errors, such as line breaks, control characters and missing angle brackets. Header names must be printable ASCII without a colon.

Example: {"Message-ID":"<ticket-123@example.com>","X-LM-Preserve-Message-ID":"true"}
​object

Metadata to track with the email (not added as email headers).

Example: {"user_id":"123","campaign_id":"welcome-2025"}
tag
​string | null · maxLength: 255 · pattern: ^[a-zA-Z0-9_-]+(?:\s…

Tag to categorize and filter emails (alphanumeric, underscores, hyphens, spaces allowed).

Example: welcome-email
​MessageTagInput[] · maxItems: 20

Reusable exact-match tags. Names must be unique and are case-sensitive.

Example: [{"name":"campaign","value":"welcome-v2"},{"name":"environment","value":"production"}]
​object

Per-email settings that override the selected route settings for this email only.

Example: {"track_opens":false,"track_clicks":true,"tls":"enforced"}
html
​string | null · minLength: 3
text
​string | null · minLength: 3
idempotency_key
​string · minLength: 1 · maxLength: 255

Optional key (1-255 characters) that makes this email safe to send again, in this or a later batch. If an email with the same key and content was accepted in the last 24 hours, its original result is returned and it is not sent again. Keys must be unique within a batch. Reusing a key with different content, or while the email with that key is still being processed, rejects the whole batch with 409 Conflict and sends nothing.

SendBatchMailRequest

​SendBatchMailItem[] · minItems: 1
SendBatchMailItem
from
​string · required
to
​string[] · minItems: 1 · required
subject
​string · maxLength: 998 · required
route
​string
cc
​string[]
bcc
​string[]
reply_to
​string[]
scheduled_at
​string · maxLength: 255

ISO 8601 or English delivery time. A time without a timezone uses UTC.

Example: tomorrow at 9am
sandbox_result
​SandboxResult · enum

The result that a Sandbox project simulates for every recipient.

Enum values:
delivered
hard_bounced
soft_bounced
deferred
failed
suppressed
spam_complaint
auto_replied
Example: hard_bounced
​object

Custom headers to include in the email. To preserve a submitted RFC Message-ID, include both Message-ID and X-LM-Preserve-Message-ID with a string value of true or 1. Header names and control values are case-insensitive; false or 0 retains replacement. Send values as plain text: Lettermint encodes non-ASCII characters and repairs small formatting errors, such as line breaks, control characters and missing angle brackets. Header names must be printable ASCII without a colon.

Example: {"Message-ID":"<ticket-123@example.com>","X-LM-Preserve-Message-ID":"true"}
​object

Metadata to track with the email (not added as email headers).

Example: {"user_id":"123","campaign_id":"welcome-2025"}
tag
​string | null · maxLength: 255 · pattern: ^[a-zA-Z0-9_-]+(?:\s…

Tag to categorize and filter emails (alphanumeric, underscores, hyphens, spaces allowed).

Example: welcome-email
​MessageTagInput[] · maxItems: 20

Reusable exact-match tags. Names must be unique and are case-sensitive.

Example: [{"name":"campaign","value":"welcome-v2"},{"name":"environment","value":"production"}]
​object

Per-email settings that override the selected route settings for this email only.

Example: {"track_opens":false,"track_clicks":true,"tls":"enforced"}
html
​string | null · minLength: 3
text
​string | null · minLength: 3
idempotency_key
​string · minLength: 1 · maxLength: 255

Optional key (1-255 characters) that makes this email safe to send again, in this or a later batch. If an email with the same key and content was accepted in the last 24 hours, its original result is returned and it is not sent again. Keys must be unique within a batch. Reusing a key with different content, or while the email with that key is still being processed, rejects the whole batch with 409 Conflict and sends nothing.

SendMailRequest

from
​string · required
to
​string[] · minItems: 1 · required
subject
​string · maxLength: 998 · required
route
​string
cc
​string[]
bcc
​string[]
reply_to
​string[]
scheduled_at
​string · maxLength: 255

ISO 8601 or English delivery time. A time without a timezone uses UTC.

Example: tomorrow at 9am
sandbox_result
​SandboxResult · enum

The result that a Sandbox project simulates for every recipient.

Enum values:
delivered
hard_bounced
soft_bounced
deferred
failed
suppressed
spam_complaint
auto_replied
Example: hard_bounced
​object

Custom headers to include in the email. To preserve a submitted RFC Message-ID, include both Message-ID and X-LM-Preserve-Message-ID with a string value of true or 1. Header names and control values are case-insensitive; false or 0 retains replacement. Send values as plain text: Lettermint encodes non-ASCII characters and repairs small formatting errors, such as line breaks, control characters and missing angle brackets. Header names must be printable ASCII without a colon.

Example: {"Message-ID":"<ticket-123@example.com>","X-LM-Preserve-Message-ID":"true"}
​object

Metadata to track with the email (not added as email headers).

Example: {"user_id":"123","campaign_id":"welcome-2025"}
tag
​string | null · maxLength: 255 · pattern: ^[a-zA-Z0-9_-]+(?:\s…

Tag to categorize and filter emails (alphanumeric, underscores, hyphens, spaces allowed).

Example: welcome-email
​MessageTagInput[] · maxItems: 20

Reusable exact-match tags. Names must be unique and are case-sensitive.

Example: [{"name":"campaign","value":"welcome-v2"},{"name":"environment","value":"production"}]
​object

Per-email settings that override the selected route settings for this email only.

Example: {"track_opens":false,"track_clicks":true,"tls":"enforced"}
html
​string | null · minLength: 3
text
​string | null · minLength: 3

TlsPolicy

string · enum
Enum values:
opportunistic
enforced

ValidationError

message
​string · required

Errors overview.

​object · required

A detailed description of each field that failed validation.