Charchy Senddocs

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:00 is Iraq time, Z is 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, not scheduled.
  • 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_at above; a past time sends it at once.
  • The new time must be before the email's expires_at, if it has one.
  • Only scheduled_at can change, and not once the email is queued or 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_at if set; otherwise validation_error.
  • A dropped email gets status expired (reason expires_at), an email.expired webhook, and is refunded.
  • Retries after a temporary failure never go past expires_at: if the next try would land after it, the email ends as failed (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_at 10 minutes from now.
  • Queued emails with expires_at leave 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_at passes — expired, reason expires_at, refunded; or
  • it has waited 3 days past its due time (its scheduled_at, or when you sent it) — expired, reason held_too_long, refunded. Transactional mail days late is worse than none.

Test mail and magic addresses are never held.

On this page