Send an email
Accepts one email and queues it (or schedules it, with `scheduled_at`). The answer comes back at once; delivery is reported by webhooks and `GET /emails/{id}`. Charged per recipient when accepted, refunded if the email is canceled, expires, is suppressed or fails for good.
Accepts one email and queues it (or schedules it, with
scheduled_at). The answer comes back at once; delivery is reported
by webhooks and GET /emails/{id}.
Charged per recipient when accepted, refunded if the email is canceled, expires, is suppressed or fails for good.
apiKeyAuthorizationBearer <token>Authorization: Bearer chy_live_… (or chy_test_…). A live key may
be sending-only, and may be locked to one domain.
Idempotency-Key?string1–256 characters, no control characters, kept 24 hours per
workspace. The same key with the same body returns the first response
again; with a different body, 409 idempotency_conflict; an empty,
too long or malformed key, 400 invalid_idempotency_key. Send one on
every request, e.g. <event-type>/<entity-id>.
1 <= length <= 256application/json- body
from*Addressaddress@domain or Name <address@domain>. Display names may be Kurdish or Arabic.
to*|array<>One address, or an array of them.
cc?|array<>One address, or an array of them.
bcc?|array<>One address, or an array of them.
reply_to?|array<>One address, or an array of them.
subject*stringlength <= 998html?stringUp to 512 KB. Give html, text or both.
text?stringUp to 512 KB. Generated from html when missing.
headers?Custom headers. Reserved, refused: From, To, Cc, Bcc, Subject,
Reply-To, DKIM-, Return-Path, Message-ID, X-SES-. No CR or LF
in names or values. List-Unsubscribe and
List-Unsubscribe-Post (RFC 8058 one-click) are allowed.
properties <= 20tags?|array<>Tags as an object ({ "type": "order" }) or as an array of
name/value pairs ([{ "name": "type", "value": "order" }]). Either
way they come back as an object.
scheduled_at?stringUp to 30 days ahead. In the past = now.
date-timeexpires_at?stringIf the email can't leave by then, it is dropped as expired and refunded.
date-timeattachments?array<>Up to 3 files, 3 MB together before base64.
items <= 3Accepted.
application/json- response
id*stringstatus*EmailStatussent = our delivery infrastructure accepted it; delivered = the
receiving server did. unknown = no delivery event 30 minutes after
an uncertain send (never re-sent; the charge stays).
With several recipients the status sums them up: complained if
any recipient complained, else bounced if any bounced, else
delivered once EVERY recipient was delivered, else
delivery_delayed if any is delayed, else sent. Each recipient's
own events are in events, with recipient.
"scheduled""queued""sending""sent""delivered""delivery_delayed""bounced""complained""canceled""expired""suppressed""failed""unknown"import { CharchySend } from "@charchy/send"const send = new CharchySend() // reads CHARCHY_SEND_KEYconst { data, error } = await send.emails.send( { from: "Darin Game <orders@daringaming.com>", to: ["customer@example.com"], replyTo: "support@daringaming.com", subject: "Your order #4821", html: "<p>Thanks for your order!</p>", tags: { type: "order_confirmation" }, }, { idempotencyKey: "order-confirmation/4821" }){ "id": "em_8f2k1x9q4w7m3n5p6r0s2t4v", "status": "queued"}