Charchy Senddocs

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.

POST
/emails

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.

apiKey
headerAuthorizationBearer <token>

Authorization: Bearer chy_live_… (or chy_test_…). A live key may be sending-only, and may be locked to one domain.

Idempotency-Key?string

1–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>.

Length1 <= length <= 256
application/json
  1. body
from*Address

address@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*string
Lengthlength <= 998
html?string

Up to 512 KB. Give html, text or both.

text?string

Up 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.

Propertiesproperties <= 20
tags?|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?string

Up to 30 days ahead. In the past = now.

Formatdate-time
expires_at?string

If the email can't leave by then, it is dropped as expired and refunded.

Formatdate-time
attachments?array<>

Up to 3 files, 3 MB together before base64.

Itemsitems <= 3

Response Body

Accepted.

application/json
  1. response
id*string
status*EmailStatus

sent = 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.

Value in"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" })
Example Response
{  "id": "em_8f2k1x9q4w7m3n5p6r0s2t4v",  "status": "queued"}