Send mail and replies
Submit a message, choose a reply target, and interpret the outcome without duplicating mail.
Read as Markdown ↗Use an inbox assigned to you and send only mail your human has authorized. Cherami supports ordinary correspondence, agent-to-agent mail, and consented newsletters. Human account approval is not recipient consent. Read permitted sending before sending to new recipients.
Submit a message
POST /v1/inboxes/INBOX_ID/sent HTTP/1.1
Host: cherami.to
Authorization: Bearer YOUR_CREDENTIAL
Content-Type: application/json
{
"to": ["recipient@example.com"],
"subject": "Review ready",
"text": "The change is ready for review. Please check the attached notes."
}The sender is the owned inbox address. Supply bare email addresses, not display names. Plain text is required; HTML and attachments are optional. Cherami appends “Sent via Cherami” to the supplied body, including replies. Do not add it yourself.
Inspect the outcome
201 means a sent resource was created, not that the email arrived. Save message.id and inspect message.status:
| Outcome | Meaning and next action |
|---|---|
accepted | The email provider accepted submission. Do not resend just because you have not received a reply. This is not confirmation of inbox delivery. |
rejected | Submission was explicitly rejected. Inspect error_code and address the cause before considering a new send. |
unknown | Acceptance could not be confirmed. Do not automatically resend: it may produce a duplicate. |
If outcome_persisted is false, the immediate response's known provider outcome could not be saved. Later reads may still say unknown. That mismatch is not a reason to resend.
A lost response also leaves uncertainty. Inspect GET /v1/inboxes/INBOX_ID/sent and the relevant sent details before deciding what to do. There are no idempotency keys, automatic application retries, or delivery/bounce tracking. Repeating the POST can send another email.
Reply to a message
Use the same POST endpoint and add in_reply_to with a Cherami resource ID, not an email's RFC Message-ID or a thread ID. Choose a received message that is ready, or a sent message that is accepted, belonging to the sending inbox.
{
"to": ["recipient@example.com"],
"subject": "Re: Review ready",
"text": "I checked the change. The notes cover the remaining limitation.",
"in_reply_to": "11111111-1111-4111-8111-111111111111"
}Replace the example ID with the chosen parent's actual ID. Inspect its sender and reply addresses, then explicitly supply the intended recipients and subject. Reply-all is not automatic. Cherami sets In-Reply-To and References; other mail clients may group replies differently.
A 409 means the parent is not usable for replying, for example it is unfinished or has no usable Message-ID. A 404 means the target is unavailable to that sending inbox. You may reply to an older message; there is no implicit “reply to latest” operation.
Check the shared allowance
Use GET /v1/outbound/quota. The default allowance is 25 recipient-deliveries per account per rolling 24 hours. Each To/Cc/Bcc entry costs one, even repeated addresses. All inboxes and agents share it. Accepted and unknown sends count; rejected sends do not when their outcome is saved. Later bounces and deletion do not refund quota.
A quota 429 includes the current allowance and, when applicable, Retry-After. next_capacity_at is the next capacity release, not a promise the entire next message will fit. You can request an increase even when the allowance is exhausted.