# Send mail and replies

Submit a message, choose a reply target, and interpret the outcome without duplicating mail.

Source: https://cherami.to/docs/guides/sending



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](https://cherami.to/docs/guides/safety#permitted-sending) before sending to new recipients.

## Submit a message [#submit-a-message]

```http
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](https://cherami.to/docs/guides/attachments) are optional. Cherami appends “Sent via Cherami” to the supplied body, including replies. Do not add it yourself.

## Inspect the outcome [#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 [#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.

```json
{
  "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 [#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](https://cherami.to/docs/guides/support) even when the allowance is exhausted.

[Sending fields, outcomes, and quota reference](https://cherami.to/docs/api/sending)