cherami.
API referenceInboxes and rules

Inspect sending rules

GET /v1/inboxes/{inbox_id}/sending-policy

Read as Markdown ↗

GET /v1/inboxes/{inbox_id}/sending-policy

Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.

Shows the inbox's recipient restrictions. They apply to every way of sending: send, reply, reply-all, forward and drafts.

With enabled: false the inbox can send to anyone, even if addresses or domains are saved. With enabled: true, every To, Cc and Bcc recipient must match an entry in addresses or domains, or the send is refused with 403 recipient_not_allowed; with both lists empty, the inbox can't send.

An address entry matches exactly: the local part is case-sensitive, and plus tags and dots count. A domain matches without regard to case and only itself, not its subdomains; international domains are listed in punycode.

These rules can be changed only in Account → Sending rules, not through the API. Sending rules guide

Parameters

ParameterLocationRequiredTypeMeaning
inbox_idpathYesstringCherami resource ID returned by the API.

curl example

Supply CHERAMI_API_KEY privately.

curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/inboxes/INBOX_ID/sending-policy" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"

Responses

HTTP 200

Success.

  • X-Request-ID: Identifies this request; include it when reporting a problem.

Content type: application/json.

Policy

{
  "inbox_id": "11111111-1111-4111-8111-111111111111",
  "enabled": true,
  "addresses": [],
  "domains": [],
  "revision": 0
}

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

internal_error: The operation failed. Retry a read; after a write the change may have happened, so recover as retry by operation describes.

  • X-Request-ID: Identifies this request; include it when reporting a problem.

Content type: application/json.

Error

Schema: Policy

FieldRequiredTypeMeaning and constraints
inbox_idYesstringCherami resource ID.
enabledYesboolean
addressesYesarray of stringmaxItems: 100
domainsYesarray of stringmaxItems: 100
revisionYesintegerSaved policy version; zero when unconfigured. minimum: 0

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.

Errors, limits and pagination · Download OpenAPI 3.1

On this page