Skip to main content
POST
/
emails
curl --request POST \
  --url https://app.lettr.com/api/emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "sender@example.com",
  "to": [
    "recipient@example.com"
  ],
  "subject": "Hello",
  "html": "<p>Hello!</p>"
}
'
{
  "message": "Email queued for delivery.",
  "data": {
    "request_id": "12345678901234567890",
    "accepted": 1,
    "rejected": 0
  }
}
Sends an email to one or more recipients. Supports HTML, plain text, AMP content, templates, merge tags, attachments, and tracking options.

Authorizations

​
Authorization
string
header
required

API key for authentication

Body

application/json

Email sending request. Required: from, subject, to, and at least one of html, text, or template_slug. When using template_slug, if project_id is not provided, the team's default project will be used.

​
from
string<email>
required

Sender email address

Maximum string length: 255
Example:

"sender@example.com"

​
subject
string
required

Email subject line

Maximum string length: 998
Example:

"Welcome to Lettr"

​
to
string<email>[]
required

Recipient email addresses

Required array length: 1 - 50 elements
Maximum string length: 255
Example:
["recipient@example.com"]
​
from_name
string | null

Sender display name

Maximum string length: 255
Example:

"Sender Name"

​
cc
string<email>[]

Carbon copy recipient email addresses

Maximum string length: 255
Example:
["cc@example.com"]
​
bcc
string<email>[]

Blind carbon copy recipient email addresses

Maximum string length: 255
Example:
["bcc@example.com"]
​
reply_to
string<email> | null

Reply-To email address

Maximum string length: 255
Example:

"reply@example.com"

​
reply_to_name
string | null

Reply-To display name

Maximum string length: 255
Example:

"Reply Name"

​
html
string | null

HTML content of the email. At least one of html or text is required, but providing both is recommended for best compatibility across email clients.

Example:

"<h1>Hello</h1><p>Welcome!</p>"

​
text
string | null

Plain text content of the email. At least one of html or text is required, but providing both is recommended for best compatibility across email clients.

Example:

"Hello\n\nWelcome!"

​
amp_html
string | null

AMP HTML content for supported email clients

​
project_id
integer | null

Project ID containing the template. If not provided when using template_slug, the team's default project will be used.

Example:

123

​
template_slug
string | null

Template slug to use for email content. When provided, the template's HTML will be used instead of the html field.

Maximum string length: 255
Example:

"welcome-email"

​
template_version
integer | null

Specific template version to use. If not provided, the active version will be used.

Required range: x >= 1
Example:

1

​
tag
string

Tag for tracking and analytics. Automatically set from template_slug if not provided.

Maximum string length: 64
Example:

"welcome-series-2024"

​
metadata
object

Custom metadata attached to the email for tracking purposes

Example:
{
  "user_id": "12345",
  "campaign": "onboarding"
}
​
substitution_data
object

Variables for template substitution in email content

Example:
{
  "first_name": "John",
  "company": "Acme Inc"
}
​
options
object

Email delivery options

​
attachments
object[]

File attachments. When provided, each attachment must include name, type, and data.

Response

Email queued for delivery. Free tier teams receive quota headers indicating their usage and limits.

​
message
string
required

Human-readable success message

Example:

"Email queued for delivery."

​
data
object
required