Send an email
POST /v1/emails — every field, what we check, what you get back, and how to read an email's status later.
POST https://api.charchy.krd/v1/emails
Authorization: Bearer chy_live_…
Content-Type: application/json
Idempotency-Key: order-confirmation/4821{
"from": "Darin Game <orders@daringaming.com>",
"to": ["customer@example.com"],
"cc": [],
"bcc": [],
"reply_to": "support@daringaming.com",
"subject": "Your order #4821",
"html": "<p>Thanks for your order! …</p>",
"text": "Thanks for your order! …",
"headers": { "X-Entity-Ref-ID": "4821" },
"attachments": [
{ "filename": "invoice.pdf", "content": "JVBERi0xLjcK…", "content_type": "application/pdf" }
],
"tags": { "type": "order_confirmation" },
"scheduled_at": "2026-11-20T09:00:00+03:00",
"expires_at": "2026-11-20T12:00:00+03:00"
}Response 200
{ "id": "em_8f2k1x9q4w7m3n5p6r0s2t4v", "status": "queued" }status is scheduled for a future scheduled_at, and suppressed when
every recipient is on your suppression list. Keep the id (em_ + 24 letters
and digits): webhooks and GET /v1/emails/{id} use it.
Fields
| Field | Type | Required | Notes |
|---|---|---|---|
from | string | yes | "Name <address>" or a bare address, on one of your workspace's verified domains. Any local part works (orders@, no-reply@). The name may be Kurdish or Arabic, up to 200 characters. |
to | string or array | yes | "customer@example.com", "Name <customer@example.com>", or an array of them. |
cc, bcc | string or array | no | Same format. to + cc + bcc together: at most 50 addresses, after duplicates are dropped. |
reply_to | string or array | no | Where replies go. Up to 5 addresses. |
subject | string | yes | Up to 998 characters. Not empty, no line breaks. |
html | string | one of the two | Up to 512 KB. |
text | string | one of the two | Up to 512 KB. Send only html and we make the text part for you. |
headers | object | no | Up to 20 custom headers. See Tags and headers. |
attachments | array | no | Up to 3 files, 3 MB together. See Logos, images and attachments. |
tags | object or array | no | Up to 10 pairs — { "type": "order" } or [{ "name": "type", "value": "order" }]. They come back in webhooks and filter the log. See Tags and headers. |
scheduled_at | string | no | ISO 8601 with a time zone, up to 30 days ahead. See Scheduling. |
expires_at | string | no | ISO 8601 with a time zone, in the future and after scheduled_at. If the email can't leave by then, it is dropped and refunded. See expires_at. |
- The whole request body may be up to 5 MB.
- Unknown fields are refused with
validation_error, so a typo can't drop a field silently.replyToanswers Did you mean "reply_to"? nullcounts as not set, for every optional field.
What we check
In this order, before anything is queued or charged. A failed check answers with its code (Errors has each one). A wrong key always answers first — never a body error.
- Your key — present (
missing_api_key), a real key that isn't revoked (invalid_api_key). - The body — valid JSON (
invalid_json), valid fields (validation_error, with thefieldnamed), size (payload_too_large), recipients (too_many_recipients), attachments (invalid_attachment), schedule (schedule_out_of_range), theIdempotency-Keyheader (invalid_idempotency_key). - Rate limit — 10 requests a second per workspace, bursts of 20
(
rate_limit_exceeded). - Idempotency — the same key seen before (
idempotency_conflict,idempotency_in_flight). - The key's domain lock — a key locked to one domain sends only from it
(
restricted_api_key). - Live keys only: sending not paused (
sending_paused), andfromon a verified domain of this workspace (sender_not_allowed,domain_not_verified). - Approval — before your workspace is approved, a live key sends only to
your team's own addresses (
not_approved). - Sending available — live sending not halted on our side
(
sending_unavailable). - Daily caps — under your rolling-day cap, or the test allowance
(
daily_limit_reached). - Balance — emails left to spend (
insufficient_balance). Only approved live sends are charged.
Addresses
- Kurdish and Arabic display names work everywhere:
"دارین گەیم <orders@daringaming.com>". We encode them for you. - International domains (
user@مثال.com) are converted to their ASCII form for you. - Non-ASCII local parts (
ئاراس@example.com) are refused withvalidation_error: too many receiving servers still can't take them. - A line break (CR or LF) in any address, subject or header is refused with
validation_error(it is how header injection works). - Addresses are stored in lowercase. The same address twice (in
toandcc, say) gets one copy.
Reserved headers
We set these, so headers can't: From, To, Cc,
Bcc, Subject, Reply-To, Sender, Date, Return-Path, Message-ID,
MIME-Version, Content-*, DKIM-*, X-SES-*. Setting one returns
validation_error. Everything else, including List-Unsubscribe, is yours —
see Tags and headers.
Suppressed addresses
An address that hard-bounced or marked your mail as spam goes on your workspace's suppression list, and we don't send to it again — this protects your domain's reputation.
- An address that only unsubscribed from your newsletters is not skipped: people who leave your newsletter still need their password reset.
- A suppressed recipient is skipped and not charged; the other recipients get
the email as usual. Each skipped recipient gets a
suppressedevent and its ownemail.suppressedwebhook. - If every recipient is suppressed, the request still succeeds with status
suppressed, and nothing is charged. - The list is under Suppressions in the dashboard, where you can let a bounced address back — see Suppressions.
Statuses
scheduled → queued → sending → sent → delivered
↘ delivery_delayed
↘ bounced
↘ complained
side exits: canceled · expired · suppressed · failed · unknown| Status | Means |
|---|---|
scheduled | Waiting for its scheduled_at. |
queued | Accepted and waiting its turn. |
sending | Being handed to our delivery infrastructure. |
sent | Our infrastructure accepted it. |
delivered | The recipient's mail server accepted it. |
delivery_delayed | The receiving server is slow or refusing for now; delivery keeps being tried. |
bounced | The receiving server refused it. A hard bounce (bounce.type permanent) also suppresses the address; a temporary one, like a full mailbox, doesn't. |
complained | The recipient marked it as spam. The address is suppressed. |
canceled | You canceled it before it left. Refunded. |
expired | It couldn't leave in time: its expires_at passed, or it was held 3 days past its due time while sending was paused. Refunded. |
suppressed | Every recipient was on the suppression list. Not charged. |
failed | It couldn't be sent — for example because your domain stopped verifying, or temporary errors went on until the retries ran out. Refunded. |
unknown | We got no answer from the delivery side and no event for 30 minutes after it was handed over. See below. |
An expired, failed or unknown event has a reason saying why, such as
expires_at, held_too_long, domain_not_verified or retries_exhausted.
Emails with several recipients
An email to several people has one status, taken from its recipients in this order:
- any recipient complained →
complained; - else any recipient bounced →
bounced; - else every recipient was delivered →
delivered; - else any recipient is delayed →
delivery_delayed; - else →
sent.
Suppressed recipients never left, so they don't count. Each recipient's
events are on the timeline with a recipient field and send their own
webhook — an email to three people where one bounces reads bounced, and the
timeline still shows the other two delivered. See Webhooks
and Events reference.
unknown
If a send times out on our side, the email may already have left, so we never
resend it. It stays sending until a delivery event settles it, and shows
unknown after 30 minutes without one. The charge stays. A later event still
moves it on to sent, delivered and so on.
Read an email
Needs a key with full permission.
import { CharchySend } from "@charchy/send"
const send = new CharchySend() // reads CHARCHY_SEND_KEY
const { data, error } = await send.emails.get("em_8f2k1x9q4w7m3n5p6r0s2t4v"){
"id": "em_8f2k1x9q4w7m3n5p6r0s2t4v",
"status": "delivered",
"from": "Darin Game <orders@daringaming.com>",
"to": ["customer@example.com"],
"cc": [],
"bcc": [],
"reply_to": ["support@daringaming.com"],
"subject": "Your order #4821",
"tags": { "type": "order_confirmation" },
"test": false,
"created_at": "2026-11-16T09:00:00.120Z",
"scheduled_at": null,
"expires_at": null,
"events": [
{ "type": "queued", "at": "2026-11-16T09:00:00.120Z" },
{ "type": "sent", "at": "2026-11-16T09:00:00.910Z" },
{ "type": "delivered", "at": "2026-11-16T09:00:02.400Z", "recipient": "customer@example.com" }
]
}Events on a test email carry "simulated": true. A bounce event carries
bounce (type, sub_type, diagnostic_code).
Emails and their events are kept for 30 days; their content for 7 days after the email was due.
List emails
Needs a key with full permission.
const { data, error } = await send.emails.list({ limit: 20, status: "bounced" })| Query | Notes |
|---|---|
limit | 1–100, default 20. Newest first. |
after | The next_cursor of the previous page, with the same filters. |
status | One status from the table above. |
tag | key:value, e.g. type:order_confirmation. |
to | A recipient address. |
{
"data": [
{
"id": "em_8f2k1x9q4w7m3n5p6r0s2t4v",
"status": "bounced",
"from": "Darin Game <orders@daringaming.com>",
"to": ["old@example.com"],
"subject": "Your order #4821",
"tags": { "type": "order_confirmation" },
"test": false,
"created_at": "2026-11-16T09:00:00.120Z",
"scheduled_at": null
}
],
"has_more": true,
"next_cursor": "…"
}next_cursoris only there whenhas_moreistrue. Treat it as opaque.tagandtofilter each page after it is read, so a page can hold fewer thanlimitemails — even none — whilehas_moreistrue. Keep followingnext_cursor.- The list covers the last 30 days.
Permissions
A sending key can send and read
GET /v1/usage. Reading, listing,
rescheduling and canceling emails need a full key (restricted_api_key
otherwise).