Scheduling and expiry
Send later with scheduled_at, change or cancel it before it leaves, and let time-sensitive emails expire with expires_at.
scheduled_at
Send later — a booking reminder the day before, a receipt at the start of business hours.
{
"from": "Clinic <bookings@clinic.example>",
"to": ["patient@example.com"],
"subject": "Reminder: your appointment tomorrow at 10:00",
"text": "…",
"scheduled_at": "2026-11-20T09:00:00+03:00"
}{ "id": "em_5k2m8x1q9w3r7v4n6p0t2c8d", "status": "scheduled" }- ISO 8601 with a time zone (
+03:00is Iraq time,Zis UTC). Without one,validation_error— it would mean a different moment on every server. - Up to 30 days ahead. Further returns
422 schedule_out_of_range. - A time in the past means now: the email is
queued, notscheduled. - Charged when you send the request; the charge stands even if your credits expire before it goes out.
Change the time
While the email is still scheduled (a key with full permission):
import { CharchySend } from "@charchy/send"
const send = new CharchySend() // reads CHARCHY_SEND_KEY
const { data, error } = await send.emails.update("em_5k2m8x1q9w3r7v4n6p0t2c8d", {
scheduledAt: "2026-11-20T08:00:00+03:00",
}){ "id": "em_5k2m8x1q9w3r7v4n6p0t2c8d", "status": "scheduled", "scheduled_at": "2026-11-20T05:00:00.000Z" }- Same rules as
scheduled_atabove; a past time sends it at once. - The new time must be before the email's
expires_at, if it has one. - Only
scheduled_atcan change, and not once the email isqueuedor later (validation_error).
Cancel
While the email is scheduled or queued (a key with full permission):
const { data, error } = await send.emails.cancel("em_5k2m8x1q9w3r7v4n6p0t2c8d"){ "id": "em_5k2m8x1q9w3r7v4n6p0t2c8d", "status": "canceled" }A canceled email is refunded and fires email.canceled; canceling again
answers the same. Once sending or later, it can't be canceled
(validation_error).
Refunds go back where the charge came from: plan emails to their plan term while it runs, credits to your balance while it hasn't expired. Past either, there is nothing to give back.
expires_at
If the email can't leave by expires_at — a long queue, sending paused or
held — we drop it instead of sending it late. A sign-in code that arrives 20
minutes after the person gave up is worse than none: they already asked for a
new one, and now they have two.
{
"from": "My App <no-reply@myapp.example>",
"to": ["user@example.com"],
"subject": "Your sign-in code: 482910",
"text": "Your code is 482910. It expires in 10 minutes.",
"expires_at": "2026-11-16T12:10:00Z"
}- Must be in the future, and after
scheduled_atif set; otherwisevalidation_error. - A dropped email gets status
expired(reasonexpires_at), anemail.expiredwebhook, and is refunded. - Retries after a temporary failure never go past
expires_at: if the next try would land after it, the email ends asfailed(retries_exhausted) and is refunded. - It is about leaving our system, not reaching the inbox: once sent, the email is the receiving server's.
- Match it to the code's lifetime: a 10-minute code gets an
expires_at10 minutes from now. - Queued emails with
expires_atleave first, soonest to expire first, so a code never waits behind your receipts.
Together, scheduled_at is the earliest an email may leave and expires_at
the latest.
Held mail
When live sending is paused for your workspace — by our automatic pauses, by a person, or by our delivery provider — or held on our side, live mail you already sent us is held, not failed: it keeps its place and goes out when sending resumes. It ends early only when:
- its
expires_atpasses —expired,reasonexpires_at, refunded; or - it has waited 3 days past its due time (its
scheduled_at, or when you sent it) —expired,reasonheld_too_long, refunded. Transactional mail days late is worse than none.
Test mail and magic addresses are never held.