Skip to main content
POST
/
api
/
v2
/
emails
/
schedule
import { Inbound } from '@inboundemail/sdk';

const inbound = new Inbound('your_api_key');

// Schedule with natural language
const { data, error } = await inbound.email.send({
  from: 'Acme <noreply@yourdomain.com>',
  to: ['customer@example.com'],
  subject: 'Scheduled Reminder',
  html: '<h1>This is your scheduled reminder!</h1>',
  text: 'This is your scheduled reminder!',
  scheduled_at: 'tomorrow at 9am',
  timezone: 'America/New_York'
});

if (error) {
  console.error('Error:', error);
} else {
  console.log('Email scheduled:', data.id);
  console.log('Will be sent at:', data.scheduled_at);
}

{
  "id": "sch_1234567890abcdef",
  "scheduled_at": "2024-12-25T14:00:00.000Z",
  "status": "scheduled",
  "timezone": "America/New_York"
}
This endpoint supports both natural language scheduling (“in 1 hour”, “tomorrow at 9am”) and ISO 8601 timestamps, making it easy to schedule emails for any future time.

​
Authentication

This endpoint requires authentication via:
  • API key auth: Bearer token in Authorization header

​
Body Parameters

​
from
string
required
Sender email address.To include a friendly name, use the format "Your Name <sender@domain.com>".
You must own and have verified the sender’s domain in your Inbound account.
You can use agent@inbnd.dev as a sender without domain verification for testing purposes. Note: This email can only be used for sending new emails, not for replying to received emails.
​
to
string | string[]
required
Recipient email address. For multiple addresses, send as an array of strings.
Combined total of all recipients (to, cc, bcc) should not exceed 50 addresses.
​
subject
string
required
Email subject.
​
scheduled_at
string
required
When to send the email. Supports two formats:Natural Language:
  • “in 30 minutes”
  • “in 2 hours”
  • “tomorrow at 9am”
  • “next Monday at 2pm”
  • “December 25 at noon”
ISO 8601 Timestamps:
  • “2024-12-25T09:00:00Z”
  • “2024-12-25T09:00:00-05:00”
The scheduled time must be at least 1 minute in the future and no more than 1 year from now.
​
timezone
string
Timezone for natural language parsing (e.g., “America/New_York”, “Europe/London”).Defaults to UTC if not provided. Only used when scheduled_at is in natural language format.
Use IANA timezone identifiers. See timezone list.
​
bcc
string | string[]
Bcc recipient email address. For multiple addresses, send as an array of strings.
​
cc
string | string[]
Cc recipient email address. For multiple addresses, send as an array of strings.
​
reply_to
string | string[]
Reply-to email address. For multiple addresses, send as an array of strings.
Also accepts replyTo (camelCase) for Resend compatibility.
​
replyTo
string | string[]
Reply-to email address (Resend-compatible camelCase format). For multiple addresses, send as an array of strings.
​
html
string
The HTML version of the message.
​
text
string
The plain text version of the message.
​
headers
object
Custom headers to add to the email.
​
tags
array
Array of tag objects for email categorization and tracking (Resend-compatible).
​
attachments
array
Array of file attachments (max 40MB total email size, 25MB per attachment, 20 attachments max).

​
Headers

​
Authorization
string
required
Bearer token for API authentication.
​
Idempotency-Key
string
Add an idempotency key to prevent duplicated scheduled emails.
  • Should be unique per API request
  • Idempotency keys expire after 24 hours
  • Have a maximum length of 256 characters

​
Request Example

import { Inbound } from '@inboundemail/sdk';

const inbound = new Inbound('your_api_key');

// Schedule with natural language
const { data, error } = await inbound.email.send({
  from: 'Acme <noreply@yourdomain.com>',
  to: ['customer@example.com'],
  subject: 'Scheduled Reminder',
  html: '<h1>This is your scheduled reminder!</h1>',
  text: 'This is your scheduled reminder!',
  scheduled_at: 'tomorrow at 9am',
  timezone: 'America/New_York'
});

if (error) {
  console.error('Error:', error);
} else {
  console.log('Email scheduled:', data.id);
  console.log('Will be sent at:', data.scheduled_at);
}

​
Response

​
id
string
required
Unique identifier for the scheduled email in Inbound’s system
​
scheduled_at
string
required
Normalized ISO 8601 timestamp of when the email will be sent
​
status
string
required
Status of the scheduled email (always “scheduled” for successful requests)
​
timezone
string
required
Timezone used for scheduling the email
{
  "id": "sch_1234567890abcdef",
  "scheduled_at": "2024-12-25T14:00:00.000Z",
  "status": "scheduled",
  "timezone": "America/New_York"
}

​
Natural Language Examples

The scheduled_at field supports intuitive natural language expressions:
  • "in 30 minutes"
  • "in 2 hours"
  • "in 3 days"
  • "in 1 week"
  • "tomorrow at 9am"
  • "next Monday at 2pm"
  • "Friday at 5:30pm"
  • "December 25 at noon"
  • "2024-12-25 at 9am"
  • "Dec 25 at 2pm"
  • "Christmas at 10am"
  • "New Year's Day at midnight"

​
Managing Scheduled Emails

After scheduling emails, you can manage them using these endpoints:

List Scheduled Emails

View all your scheduled emails with filtering and pagination

Get Scheduled Email

Retrieve details of a specific scheduled email

Cancel Scheduled Email

Cancel a scheduled email before it’s sent

​
Important Notes

Domain Verification Required: You can only send emails from domains that you own and have verified in your Inbound account. Attempting to send from an unverified domain will result in a 403 error.
Scheduling Limits: Emails can be scheduled up to 1 year in advance and must be at least 1 minute in the future. The system processes scheduled emails every minute.
Idempotency: Use the Idempotency-Key header to ensure emails aren’t scheduled multiple times in case of network issues or retries.
Timezone Handling: When using natural language scheduling, always specify a timezone to ensure emails are sent at the expected local time.
1.0 - ✅