Send

Send a single transactional email or a batch of them in one request, with attachments, custom headers and tags.

Send an email

POST

https://api.lettermint.co/v1

/send

x-lettermint-token (header)

The request body can be at most 25 MB, including base64-encoded attachments. A larger request is rejected with a 413 Request Entity Too Large before it reaches the API, and the email is not sent.

Send an email › Headers

x-lettermint-token

string

Project API token for the project sending this email.

Idempotency-Key

string

Optional key (1-255 characters) that makes the request safe to retry. Repeating a request with the same key and body within 24 hours returns the original response instead of sending again.

Send an email › Request Body

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

MessageAttachmentInput[]

Send an email › Responses

Message accepted for delivery

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: message_id, status
	type = object · requires: message_id, status, scheduled_at

Properties for PendingSendMailResponse:

An accepted message that is queued for delivery.

PendingSendMailResponse

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

POST/send

curl -X POST https://api.lettermint.co/v1/send \
  -H "x-lettermint-token: $LETTERMINT_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"John Doe <john@example.com>","to":["recipient@example.com"],"subject":"Hello","text":"Sent with Lettermint."}'

Example Request Body

{
  "route": "route",
  "from": "from",
  "to": [
    "string"
  ],
  "cc": [
    "string"
  ],
  "bcc": [
    "string"
  ],
  "reply_to": [
    "string"
  ],
  "subject": "subject",
  "scheduled_at": "tomorrow at 9am",
  "sandbox_result": "hard_bounced",
  "headers": {
    "Message-ID": "<ticket-123@example.com>",
    "X-LM-Preserve-Message-ID": "true"
  },
  "metadata": {
    "user_id": "123",
    "campaign_id": "welcome-2025"
  },
  "tag": "welcome-email",
  "tags": [
    {
      "name": "campaign",
      "value": "welcome-v2"
    },
    {
      "name": "environment",
      "value": "production"
    }
  ],
  "settings": {
    "track_opens": false,
    "track_clicks": true,
    "tls": "enforced"
  },
  "html": "html",
  "text": "text",
  "attachments": [
    {
      "filename": "filename",
      "content": "content",
      "content_type": "application/pdf",
      "content_id": "logo-image"
    }
  ]
}

json

Example Responses

{
  "message_id": "message_id",
  "status": "pending",
  "sandbox": true,
  "sandbox_result": "delivered"
}

json

application/json

Send multiple emails in a batch

POST

https://api.lettermint.co/v1

/send/batch

x-lettermint-token (header)

Send up to 500 emails in a single request. Each email in the batch supports the same parameters as the single send endpoint. The whole request body can be at most 25 MB, including base64-encoded attachments. A larger request is rejected with a 413 Request Entity Too Large before it reaches the API, and none of its emails are sent, so split larger batches into several requests.

Emails are accepted in order. When an email fails, the emails before it may already be accepted and are not rolled back. The error then lists them in details.accepted, with their index in the batch and their message_id. Give each email an idempotency_key to retry safely: a retry returns the original result of every email that was accepted and sends only the rest.

Send multiple emails in a batch › Headers

x-lettermint-token

string

Project API token for the project sending this email.

Idempotency-Key

string

Optional key (1-255 characters) that makes the whole request safe to retry. Repeating a request with the same key and body within 24 hours returns the original response instead of sending again. To retry part of a batch, give each email an idempotency_key instead.

Send multiple emails in a batch › Request Body

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

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

MessageAttachmentInput[]

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.

Send multiple emails in a batch › Responses

Array of message IDs and their status

array

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: message_id, status
	type = object · requires: message_id, status, scheduled_at

Properties for PendingSendMailResponse:

An accepted message that is queued for delivery.

PendingSendMailResponse

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

POST/send/batch

curl https://api.lettermint.co/v1/send/batch \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-lettermint-token: <api-key>' \
  --data '[
  {
    "route": "route",
    "from": "from",
    "to": [
      "string"
    ],
    "cc": [
      "string"
    ],
    "bcc": [
      "string"
    ],
    "reply_to": [
      "string"
    ],
    "subject": "subject",
    "scheduled_at": "tomorrow at 9am",
    "sandbox_result": "hard_bounced",
    "headers": {
      "Message-ID": "<ticket-123@example.com>",
      "X-LM-Preserve-Message-ID": "true"
    },
    "metadata": {
      "user_id": "123",
      "campaign_id": "welcome-2025"
    },
    "tag": "welcome-email",
    "tags": [
      {
        "name": "campaign",
        "value": "welcome-v2"
      },
      {
        "name": "environment",
        "value": "production"
      }
    ],
    "settings": {
      "track_opens": false,
      "track_clicks": true,
      "tls": "enforced"
    },
    "html": "html",
    "text": "text",
    "attachments": [
      {
        "filename": "filename",
        "content": "content",
        "content_type": "application/pdf",
        "content_id": "logo-image"
      }
    ],
    "idempotency_key": "idempotency_key"
  }
]'

Example Request Body

[
  {
    "route": "route",
    "from": "from",
    "to": [
      "string"
    ],
    "cc": [
      "string"
    ],
    "bcc": [
      "string"
    ],
    "reply_to": [
      "string"
    ],
    "subject": "subject",
    "scheduled_at": "tomorrow at 9am",
    "sandbox_result": "hard_bounced",
    "headers": {
      "Message-ID": "<ticket-123@example.com>",
      "X-LM-Preserve-Message-ID": "true"
    },
    "metadata": {
      "user_id": "123",
      "campaign_id": "welcome-2025"
    },
    "tag": "welcome-email",
    "tags": [
      {
        "name": "campaign",
        "value": "welcome-v2"
      },
      {
        "name": "environment",
        "value": "production"
      }
    ],
    "settings": {
      "track_opens": false,
      "track_clicks": true,
      "tls": "enforced"
    },
    "html": "html",
    "text": "text",
    "attachments": [
      {
        "filename": "filename",
        "content": "content",
        "content_type": "application/pdf",
        "content_id": "logo-image"
      }
    ],
    "idempotency_key": "idempotency_key"
  }
]

json

Example Responses

[
  {
    "message_id": "message_id",
    "status": "pending",
    "sandbox": true,
    "sandbox_result": "delivered"
  }
]

json

application/json

Generic