Forward a message
POST /v1/inboxes/{inbox_id}/forward
Read as Markdown ↗POST /v1/inboxes/{inbox_id}/forward
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Forwards message_id, a ready received message or an accepted sent message in the sending inbox, to the recipients in to, cc and bcc. Recipients are used exactly as given, with the limits of send. An optional note goes above the forwarded message.
The forward carries a header block with the original From, Date, Subject, To and Cc (never Bcc), then the original text and HTML as they are, quoted history included: check them for anything the new recipients shouldn't see. The subject gets Fwd: unless it already starts with Fw: or Fwd:. A forward starts a new conversation.
The original attachments, embedded images included, are attached unless include_attachments is false, which leaves out every file, so images in the HTML may not display.
Outcomes are those of send, and retries those of reply.
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: ForwardInput
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
message_id | Yes | string | ID of a ready received message or an accepted sent message in this inbox. pattern: ^[a-f0-9-]{36}$ |
to | Yes | array of Mailbox | maxItems: 50 minItems: 1 |
cc | No | array of Mailbox | maxItems: 50 |
bcc | No | array of Mailbox | maxItems: 50 |
note | No | string | Optional plain-text introduction above the forwarded message. |
include_attachments | No | boolean | false leaves out every original file, embedded images included. default: true |
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.
{
"message_id": "22222222-2222-4222-8222-222222222222",
"to": [
{
"address": "recipient@example.com"
}
],
"note": "For your review.",
"idempotency_key": "RETAIN_A_UNIQUE_SEND_KEY"
}curl --silent --show-error --include --request POST \
"https://cherami.to/v1/inboxes/INBOX_ID/forward" \
--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.
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: Label
1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.
string. x-max-utf8-bytes: 128