Skip to main content
POST
/
emails
/
scheduled
Schedule Email
curl --request POST \
  --url https://app.lettr.com/api/emails/scheduled \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "sender@example.com",
  "from_name": "Sender Name",
  "to": [
    "recipient@example.com"
  ],
  "subject": "Scheduled Newsletter",
  "html": "<h1>Hello</h1><p>This email was scheduled!</p>",
  "scheduled_at": "2024-01-16T10:00:00Z",
  "options": {
    "click_tracking": true,
    "open_tracking": true
  }
}
'
{
  "message": "Email scheduled for delivery.",
  "data": {
    "request_id": "12345678901234567890",
    "accepted": 1,
    "rejected": 0
  }
}
Schedule a transactional email for future delivery. Accepts the same payload as POST /emails with an additional required scheduled_at field.

Authorizations

​
Authorization
string
header
required

API key for authentication

Body

application/json

Schedule email request. Extends the standard send email request with a required scheduled_at field.

​
from
string<email>
required

Sender email address

Maximum string length: 255
Example:

"sender@example.com"

​
to
string<email>[]
required

Recipient email addresses

Required array length: 1 - 50 elements
Maximum string length: 255
Example:
["recipient@example.com"]
​
scheduled_at
string<date-time>
required

The UTC date/time when the email should be sent. Must be at least 5 minutes in the future and within 3 days.

Example:

"2024-01-16T10:00:00Z"

​
from_name
string | null

Sender display name

Maximum string length: 255
Example:

"Sender Name"

​
subject
string | null

Email subject line. Required when not using a template. When using template_slug, defaults to the template's subject (or template name as fallback). If provided alongside a template, overrides the template subject.

Maximum string length: 998
Example:

"Welcome to Lettr"

​
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"
}
​
headers
object

Custom email headers. Up to 10 headers allowed. Standard envelope headers (From, To, Subject, etc.), SparkPost internal headers (X-MSYS-API), and List-Unsubscribe and List-Unsubscribe-Post headers are managed by the system and cannot be set manually.

Example:
{
  "X-Mailer": "MyApp/1.0",
  "X-Custom-ID": "abc-123"
}
​
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 scheduled 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