Send a message
POST /v1/inboxes/{inbox_id}/sent
Read as Markdown ↗POST /v1/inboxes/{inbox_id}/sent
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Sends an email from the inbox. Send only permitted mail: to recipients who asked to hear from this inbox. To save a message for review or to send later, create a draft instead.
Request fields
Recipients are objects with an address and an optional name, never strings such as Alex <alex@example.com>. Mail goes out from the inbox's address with its sender_name. Your sent copy keeps Bcc recipients.
Cherami adds a "Sent via Cherami" line at the end of the text and HTML bodies; don't add one yourself. Sent copies you read back include it.
Reply targets
To answer a message while choosing recipients and subject yourself, set in_reply_to to its ID: a ready received message or an accepted sent message in the same inbox that has a Message-ID header. It is a Cherami resource ID, not an RFC Message-ID or a thread ID. Cherami sets the reply headers so the email joins that conversation. To have recipients and subject derived for you, use reply or reply-all.
Response and outcomes
201 means the attempt was recorded, not that the email went out. Check message.status:
accepted: the provider took the message. This is not delivery: Cherami doesn't report delivery or bounces.rejected: the provider refused it before accepting, so nothing was sent and the recipients aren't charged.error_codesays why: withE_RECIPIENT_SUPPRESSED, a suppressed recipient refused the whole message, so send again without that address; withE_RATE_LIMIT_EXCEEDEDorE_DAILY_LIMIT_EXCEEDED, send again later. A new attempt needs a new key.unknown: acceptance couldn't be confirmed, so the email may have gone out, and the status staysunknown. Treat it as possibly sent rather than sending it again: a resend can deliver a duplicate.
Accepted and unknown attempts are charged one unit per recipient.
When outcome_persisted is false, later reads may still say unknown: keep this response as the record of the outcome, and don't resend because a later read disagrees.
Retry a send with an idempotency key
Include an idempotency_key, a value you choose once per email, and save it with the exact request before sending. If the response is lost or you get a 5xx such as 503 outbound_unavailable, repeat the exact request with the same key within 24 hours of your first attempt.
A match returns 200 with replayed: true and the original message; check message.status as above. It never sends or charges again. Keys are unique across the account: reusing one for a different request, on any inbox or endpoint, returns 409 idempotency_conflict.
A request refused before sending (an invalid field, a blocked recipient, no allowance) leaves its key unused, so you can correct it and send with the same key. Use a new key only for a new email, never to get past an uncertain result.
After 24 hours, or if you sent without a key, look for the email in sent messages before sending again: an unprotected repeat sends a second email.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Cherami resource ID returned by the API. |
Request body
JSON object, at most 8 MiB in total.
Schema: SendInput
At most 50 To, Cc and Bcc recipients in total and 32 attachments. The whole email, counting text, HTML and base64 attachments, must fit in 5 MiB. Cherami sets From and the other headers.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
to | Yes | array of Mailbox | maxItems: 50 minItems: 1 |
cc | No | array of Mailbox | maxItems: 50 |
bcc | No | array of Mailbox | maxItems: 50 |
subject | Yes | string | No control characters; at most 998 UTF-8 bytes. Must not be blank. x-max-utf8-bytes: 998 |
text | Yes | string | Required nonblank plain text. |
html | No | string | HTML alternative, sent as supplied. |
attachments | No | array of AttachmentInput or null | Omitted, null or [] means no attachments. |
in_reply_to | No | string | ID of a ready received message or an accepted sent message in this inbox that has a Message-ID header. pattern: ^[a-f0-9-]{36}$ |
labels | No | array of Label | Label names, case-sensitive; order and duplicates don't matter. maxItems: 32 |
idempotency_key | No | string | Your unique value for this one operation. Save it with the exact request before sending; repeating that request with the same key within 24 hours returns what the first one did instead of acting again. pattern: ^[A-Za-z0-9_-]{1,128}$ |
Unknown fields are rejected.
curl example
Supply CHERAMI_API_KEY privately.
Save the payload as request.json, replacing the example values.
{
"to": [
{
"address": "recipient@example.com",
"name": "Alex"
}
],
"subject": "Notes",
"text": "Here are the notes.",
"idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY"
}curl --silent --show-error --include --request POST \
"https://cherami.to/v1/inboxes/INBOX_ID/sent" \
--header "Authorization: Bearer $CHERAMI_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
HTTP 200
A retry matched an earlier request: this is that request's result as it is now. Nothing new was created or sent.
X-Request-ID: Identifies this request; include it when reporting a problem.Location: Relative URL of the resulting resource.
Content type: application/json.
All of these schemas apply.
Part 1
Part 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
replayed | Yes | true | |
idempotency_expires_at | Yes | string | When the key stops protecting retries. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
{
"limited": false,
"message": {
"id": "33333333-3333-4333-8333-333333333333",
"inbox_id": "11111111-1111-4111-8111-111111111111",
"created_at": "2026-10-01T00:00:00.000Z",
"recipient_count": 1,
"status": "unknown",
"provider_message_id": null,
"error_code": null,
"thread_id": "44444444-4444-4444-8444-444444444444",
"in_reply_to": null,
"labels": []
},
"outcome_persisted": true,
"replayed": true,
"idempotency_expires_at": "2026-10-02T00:00:00.000Z"
}HTTP 201
Attempt recorded; check message.status.
X-Request-ID: Identifies this request; include it when reporting a problem.Location: Relative URL of the resulting resource.
Content type: application/json.
All of these schemas apply.
Part 1
Part 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
replayed | No | false |
HTTP 400
invalid_json: Send a valid UTF-8 JSON object, not an array or scalar.
invalid_message: Correct the recipients, subject, body, in_reply_to, attachments or reply and forward fields as the message describes.
invalid_name: Use plain text without control characters, at most 256 UTF-8 bytes after trimming. The message names the field.
invalid_labels: Correct the label name, label change, filter group or discovery prefix the message names.
invalid_idempotency_key: Use 1–128 ASCII letters, digits, hyphens or underscores.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 401
unauthorized: Send a valid API key as Authorization: Bearer <key>. If the key stopped working, get a new one through recovery.
X-Request-ID: Identifies this request; include it when reporting a problem.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 403
operation_not_allowed: Sending, or deletion and restore, is turned off for this account; the message says which. Contact hello@cherami.to.
recipient_not_allowed: Nothing was sent: the inbox's sending rules block one or more recipients, which the message lists. Use allowed recipients, or ask the account owner to allow them; do not send through another inbox to get around the rules.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 404
not_found: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 409
reply_not_ready: The source cannot be replied to or forwarded yet. A received message must have processing_status ready; a sent message must have status accepted.
reply_headers_unavailable: The target has no usable Message-ID to reply to. Send a new message without in_reply_to.
idempotency_conflict: The key was first used with different input. To recover that request, repeat it with its original inbox and payload; a different request needs its own key.
idempotency_result_unavailable: The key already created an inbox, draft or send whose result has since been deleted. Nothing new was created or sent; do not repeat the request under a new key. If a sent message is still in Trash, restore it to read the outcome.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 413
body_too_large: Reduce the JSON request to the operation's body limit.
message_too_large: The message exceeds 5 MiB counting text, HTML and base64 attachment content, or a forwarded original has more than 32 attachments. Reduce the content or attachments; for a forward, set include_attachments to false or attach selected files to a new message.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 429
outbound_limit_reached: The rolling 24-hour sending allowance cannot cover this message, at one charge per recipient. With reason temporary_exhaustion, retry at sufficient_capacity_at; with message_exceeds_allowance, the message needs more than the whole allowance: reduce its recipients or request a higher allowance. See sending allowance.
X-Request-ID: Identifies this request; include it when reporting a problem.Retry-After: Seconds to wait before retrying. For sending allowance it matches sufficient_capacity_at.
Content type: application/json.
HTTP 503
content_unavailable: Stored content could not be read. Retry later.
outbound_unavailable: The request failed. If it was a send, reply or forward, its outcome is unknown: repeat it with the same idempotency key and unchanged payload within 24 hours of the first request; without a key, check sent messages before sending again. Retry a read.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
Schema: SendReceipt
accepted in message.status means the provider took the message, not that it was delivered.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
limited | Yes | false | |
message | Yes | SentMetadata | |
outcome_persisted | Yes | boolean | false: this response is the only record of the outcome; keep it rather than resending. |
replayed | No | boolean | true when a retry matched an earlier request: the result is that request's, and nothing new was created or sent. |
idempotency_expires_at | No | string | When the key stops protecting retries. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
Schema: SentMetadata
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
inbox_id | Yes | string | Cherami resource ID. |
created_at | Yes | string | UTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
recipient_count | Yes | integer | minimum: 0 |
status | Yes | "accepted" or "rejected" or "unknown" | |
provider_message_id | Yes | string or null | Message-ID the provider assigned when it accepted the message. |
error_code | Yes | string or null | Reason code for a rejected or unknown outcome, such as E_RECIPIENT_SUPPRESSED or acceptance_unknown. |
thread_id | Yes | string or null | |
in_reply_to | Yes | string or null | |
labels | Yes | array of string |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
message | Yes | string | Explanation of this case; its wording can change. |
Schema: QuotaError
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object | |
quota | Yes | Quota | |
requested_recipients | Yes | integer | Recipients this message needs, one per To, Cc and Bcc entry. minimum: 0 |
reason | Yes | "temporary_exhaustion" or "message_exceeds_allowance" | temporary_exhaustion: enough capacity returns at sufficient_capacity_at. message_exceeds_allowance: the message needs more than the whole allowance, so waiting won't help. |
sufficient_capacity_at | Yes | string or null | When this message will fit; null with message_exceeds_allowance. |
guidance | Yes | string | What keeps working while sending is limited. |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | "outbound_limit_reached" | |
message | Yes | string |
Schema: Quota
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
allowance | Yes | integer | Recipients the account can send to in any 24 hours. minimum: 0 |
used | Yes | integer | Recipients charged in the last 24 hours. minimum: 0 |
remaining | Yes | integer | Recipients you can send to now. minimum: 0 |
next_capacity_at | Yes | string or null | When the next units return; null when nothing is charged. |
next_capacity_amount | Yes | integer | Recipients that become available at next_capacity_at. minimum: 0 |
window_hours | Yes | 24 | |
unit | Yes | "recipient_deliveries" | One unit per To, Cc or Bcc recipient. |
increase_request | Yes | string | How to ask for a larger allowance. |
policy_url | Yes | string |
Schema: Mailbox
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
address | Yes | string | Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. maxLength: 254 |
name | No | string | Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. x-max-utf8-bytes: 256 |
Unknown fields are rejected.
Schema: AttachmentInput
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
filename | Yes | string | At most 255 UTF-8 bytes, without control characters, slashes or backslashes. minLength: 1 x-max-utf8-bytes: 255 |
type | Yes | string | MIME type without parameters. maxLength: 127 pattern: ^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$ |
content | Yes | string | The file's bytes as padded base64, without line breaks. contentEncoding: base64 pattern: ^[A-Za-z0-9+/]*={0,2}$ |
Unknown fields are rejected.
Schema: Label
1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.
string. x-max-utf8-bytes: 128