Scheduling
Send an email later, reschedule it or cancel it.
Add scheduled_at to POST /emails to send the email later. The email is stored with status scheduled and sent at that time.
curl -X POST https://api.usend.et/emails \
-H "Authorization: Bearer us_123456789" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <[email protected]>",
"to": ["[email protected]"],
"subject": "Your trial ends tomorrow",
"text": "Upgrade any time from your account page.",
"scheduled_at": "2026-10-20T09:00:00Z"
}'const { data, error } = await usend.emails.send({
from: 'Acme <[email protected]>',
to: ['[email protected]'],
subject: 'Your trial ends tomorrow',
text: 'Upgrade any time from your account page.',
scheduled_at: '2026-10-20T09:00:00Z',
});email = usend.emails.send({
"from": "Acme <[email protected]>",
"to": ["[email protected]"],
"subject": "Your trial ends tomorrow",
"text": "Upgrade any time from your account page.",
"scheduled_at": "2026-10-20T09:00:00Z",
})scheduledAt is accepted as an alias of scheduled_at.
Accepted formats
scheduled_at accepts an ISO 8601 timestamp or a short English phrase.
| Example | Meaning |
|---|---|
2026-10-20T09:00:00Z | ISO 8601 with a time zone (recommended). |
2026-10-20T12:00:00+03:00 | ISO 8601 with an offset. |
2026-10-20T09:00:00 | No time zone: read as UTC. |
in 30 min | Relative to now. Units: s, sec, seconds, m, min, minutes, h, hr, hours, d, days, w, weeks. |
in 2 hours | Relative to now. |
tomorrow | Tomorrow at 09:00 UTC. |
tomorrow at 9am, tomorrow at 14:30, tomorrow at 5:15pm | Tomorrow at that time, UTC. |
Phrases are always interpreted in UTC. Use an ISO timestamp with an offset when you need a local time.
Limits
- The time must be in the future (a minute of clock skew is tolerated) and at most 30 days ahead.
- Batch emails cannot be scheduled.
- Sandbox rules and quotas are checked when you schedule the email, and the email counts toward the quota of the day you scheduled it.
Reschedule
Change the time of a scheduled email with PATCH /emails/{id}. The same formats and limits apply.
curl -X PATCH https://api.usend.et/emails/4ef9a417-02e9-4d39-ad75-9611e0fcc33c \
-H "Authorization: Bearer us_123456789" \
-H "Content-Type: application/json" \
-d '{ "scheduled_at": "in 1 hour" }'await usend.emails.update({
id: '4ef9a417-02e9-4d39-ad75-9611e0fcc33c',
scheduled_at: 'in 1 hour',
});usend.emails.update("4ef9a417-02e9-4d39-ad75-9611e0fcc33c", "in 1 hour"){ "object": "email", "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }Cancel
Cancel a scheduled email with POST /emails/{id}/cancel. Its status becomes canceled and an email.canceled event is recorded.
curl -X POST https://api.usend.et/emails/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/cancel \
-H "Authorization: Bearer us_123456789"await usend.emails.cancel('4ef9a417-02e9-4d39-ad75-9611e0fcc33c');usend.emails.cancel("4ef9a417-02e9-4d39-ad75-9611e0fcc33c")Only emails that are still scheduled can be rescheduled or canceled. Once an email has started sending, both calls fail with 422 validation_error.
Broadcasts can be scheduled too: see Broadcasts.