Skip to main content

​
Postponed Sending

Schedule emails to be delivered at a specific date and time.

​
Schedule an Email

Use the scheduledAt parameter with an ISO 8601 timestamp: 
await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Scheduled Reminder',
  html: '<p>This is your scheduled reminder!</p>',
  scheduledAt: '2024-12-25T09:00:00Z'
});

​
Response

Scheduled emails return a scheduled status: 
{
  "id": "email_123abc",
  "status": "scheduled",
  "scheduledAt": "2024-12-25T09:00:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Cancel a Scheduled Email

Cancel before it’s sent: 
await lettr.emails.cancel('email_123abc');

​
Reschedule an Email

Update the scheduled time: 
await lettr.emails.update('email_123abc', {
  scheduledAt: '2024-12-26T09:00:00Z'
});

​
Timezone Handling

Always use UTC times with the Z suffix: 
// Convert local time to UTC
const localDate = new Date('2024-12-25T09:00:00');
const utcString = localDate.toISOString();

await lettr.emails.send({
  // ...
  scheduledAt: utcString
});

​
Scheduling Limits

LimitValue
Maximum schedule time30 days in advance
Minimum schedule time1 minute from now
Emails scheduled more than 30 days in advance will be rejected. For longer delays, consider using a job scheduler like cron or your application’s queue system.

​
Use Cases

Time-Zone Optimized Delivery

Send emails when recipients are most likely to read them.

Drip Campaigns

Schedule a series of emails over time.

Event Reminders

Send reminders before appointments or events.

Business Hours Delivery

Ensure emails arrive during work hours.