cherami.
API referenceSending and allowance

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_code says why: with E_RECIPIENT_SUPPRESSED, a suppressed recipient refused the whole message, so send again without that address; with E_RATE_LIMIT_EXCEEDED or E_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 stays unknown. 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

ParameterLocationRequiredTypeMeaning
inbox_idpathYesstringCherami 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.

FieldRequiredTypeMeaning and constraints
toYesarray of MailboxmaxItems: 50 minItems: 1
ccNoarray of MailboxmaxItems: 50
bccNoarray of MailboxmaxItems: 50
subjectYesstringNo control characters; at most 998 UTF-8 bytes. Must not be blank. x-max-utf8-bytes: 998
textYesstringRequired nonblank plain text.
htmlNostringHTML alternative, sent as supplied.
attachmentsNoarray of AttachmentInput or nullOmitted, null or [] means no attachments.
in_reply_toNostringID of a ready received message or an accepted sent message in this inbox that has a Message-ID header. pattern: ^[a-f0-9-]{36}$
labelsNoarray of LabelLabel names, case-sensitive; order and duplicates don't matter. maxItems: 32
idempotency_keyNostringYour 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.json

Responses

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

SendReceipt

Part 2

FieldRequiredTypeMeaning and constraints
replayedYestrue
idempotency_expires_atYesstringWhen 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

SendReceipt

Part 2

FieldRequiredTypeMeaning and constraints
replayedNofalse

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.

Error

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.

Error

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.

Error

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.

Error

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.

Error

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.

Error

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.

Error

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.

QuotaError

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.

Error

Schema: SendReceipt

accepted in message.status means the provider took the message, not that it was delivered.

FieldRequiredTypeMeaning and constraints
limitedYesfalse
messageYesSentMetadata
outcome_persistedYesbooleanfalse: this response is the only record of the outcome; keep it rather than resending.
replayedNobooleantrue when a retry matched an earlier request: the result is that request's, and nothing new was created or sent.
idempotency_expires_atNostringWhen 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

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
created_atYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
recipient_countYesintegerminimum: 0
statusYes"accepted" or "rejected" or "unknown"
provider_message_idYesstring or nullMessage-ID the provider assigned when it accepted the message.
error_codeYesstring or nullReason code for a rejected or unknown outcome, such as E_RECIPIENT_SUPPRESSED or acceptance_unknown.
thread_idYesstring or null
in_reply_toYesstring or null
labelsYesarray of string

Schema: Error

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation of this case; its wording can change.

Schema: QuotaError

FieldRequiredTypeMeaning and constraints
errorYesobject
quotaYesQuota
requested_recipientsYesintegerRecipients this message needs, one per To, Cc and Bcc entry. minimum: 0
reasonYes"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_atYesstring or nullWhen this message will fit; null with message_exceeds_allowance.
guidanceYesstringWhat keeps working while sending is limited.

error fields

FieldRequiredTypeMeaning and constraints
codeYes"outbound_limit_reached"
messageYesstring

Schema: Quota

FieldRequiredTypeMeaning and constraints
allowanceYesintegerRecipients the account can send to in any 24 hours. minimum: 0
usedYesintegerRecipients charged in the last 24 hours. minimum: 0
remainingYesintegerRecipients you can send to now. minimum: 0
next_capacity_atYesstring or nullWhen the next units return; null when nothing is charged.
next_capacity_amountYesintegerRecipients that become available at next_capacity_at. minimum: 0
window_hoursYes24
unitYes"recipient_deliveries"One unit per To, Cc or Bcc recipient.
increase_requestYesstringHow to ask for a larger allowance.
policy_urlYesstring

Schema: Mailbox

FieldRequiredTypeMeaning and constraints
addressYesstringBare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. maxLength: 254
nameNostringOptional 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

FieldRequiredTypeMeaning and constraints
filenameYesstringAt most 255 UTF-8 bytes, without control characters, slashes or backslashes. minLength: 1 x-max-utf8-bytes: 255
typeYesstringMIME type without parameters. maxLength: 127 pattern: ^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$
contentYesstringThe 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

Errors, limits and pagination · Download OpenAPI 3.1

On this page