cherami.
API referenceSending and allowance

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

ParameterLocationRequiredTypeMeaning
inbox_idpathYesstringCherami resource ID returned by the API.

Request body

JSON object, at most 8 MiB in total.

Schema: ForwardInput

FieldRequiredTypeMeaning and constraints
message_idYesstringID of a ready received message or an accepted sent message in this inbox. pattern: ^[a-f0-9-]{36}$
toYesarray of MailboxmaxItems: 50 minItems: 1
ccNoarray of MailboxmaxItems: 50
bccNoarray of MailboxmaxItems: 50
noteNostringOptional plain-text introduction above the forwarded message.
include_attachmentsNobooleanfalse leaves out every original file, embedded images included. default: true
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.

{
  "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.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.

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: 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