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.