Charchy Senddocs

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

FieldTypeRequiredNotes
fromstringyes"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.
tostring or arrayyes"customer@example.com", "Name <customer@example.com>", or an array of them.
cc, bccstring or arraynoSame format. to + cc + bcc together: at most 50 addresses, after duplicates are dropped.
reply_tostring or arraynoWhere replies go. Up to 5 addresses.
subjectstringyesUp to 998 characters. Not empty, no line breaks.
htmlstringone of the twoUp to 512 KB.
textstringone of the twoUp to 512 KB. Send only html and we make the text part for you.
headersobjectnoUp to 20 custom headers. See Tags and headers.
attachmentsarraynoUp to 3 files, 3 MB together. See Logos, images and attachments.
tagsobject or arraynoUp to 10 pairs — { "type": "order" } or [{ "name": "type", "value": "order" }]. They come back in webhooks and filter the log. See Tags and headers.
scheduled_atstringnoISO 8601 with a time zone, up to 30 days ahead. See Scheduling.
expires_atstringnoISO 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. replyTo answers Did you mean "reply_to"?
  • null counts 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.

  1. Your key — present (missing_api_key), a real key that isn't revoked (invalid_api_key).
  2. The body — valid JSON (invalid_json), valid fields (validation_error, with the field named), size (payload_too_large), recipients (too_many_recipients), attachments (invalid_attachment), schedule (schedule_out_of_range), the Idempotency-Key header (invalid_idempotency_key).
  3. Rate limit — 10 requests a second per workspace, bursts of 20 (rate_limit_exceeded).
  4. Idempotency — the same key seen before (idempotency_conflict, idempotency_in_flight).
  5. The key's domain lock — a key locked to one domain sends only from it (restricted_api_key).
  6. Live keys only: sending not paused (sending_paused), and from on a verified domain of this workspace (sender_not_allowed, domain_not_verified).
  7. Approval — before your workspace is approved, a live key sends only to your team's own addresses (not_approved).
  8. Sending available — live sending not halted on our side (sending_unavailable).
  9. Daily caps — under your rolling-day cap, or the test allowance (daily_limit_reached).
  10. 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 with validation_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 to and cc, 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 suppressed event and its own email.suppressed webhook.
  • 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
StatusMeans
scheduledWaiting for its scheduled_at.
queuedAccepted and waiting its turn.
sendingBeing handed to our delivery infrastructure.
sentOur infrastructure accepted it.
deliveredThe recipient's mail server accepted it.
delivery_delayedThe receiving server is slow or refusing for now; delivery keeps being tried.
bouncedThe receiving server refused it. A hard bounce (bounce.type permanent) also suppresses the address; a temporary one, like a full mailbox, doesn't.
complainedThe recipient marked it as spam. The address is suppressed.
canceledYou canceled it before it left. Refunded.
expiredIt couldn't leave in time: its expires_at passed, or it was held 3 days past its due time while sending was paused. Refunded.
suppressedEvery recipient was on the suppression list. Not charged.
failedIt couldn't be sent — for example because your domain stopped verifying, or temporary errors went on until the retries ran out. Refunded.
unknownWe 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:

  1. any recipient complained → complained;
  2. else any recipient bounced → bounced;
  3. else every recipient was delivered → delivered;
  4. else any recipient is delayed → delivery_delayed;
  5. 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" })
QueryNotes
limit1–100, default 20. Newest first.
afterThe next_cursor of the previous page, with the same filters.
statusOne status from the table above.
tagkey:value, e.g. type:order_confirmation.
toA 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_cursor is only there when has_more is true. Treat it as opaque.
  • tag and to filter each page after it is read, so a page can hold fewer than limit emails — even none — while has_more is true. Keep following next_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).

On this page