Delete an inbox
DELETE /v1/inboxes/{inbox_id}
Read as Markdown ↗DELETE /v1/inboxes/{inbox_id}
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
DELETE /v1/inboxes/{inbox_id} returns 202.
Permanently deletes the inbox and its received mail, drafts, sent copies, attachments, and threads, including unfinished messages. Confirm the specific inbox and destructive scope with the human before calling it, especially with shared access. The API does not provide a separate approval step.
The slot is freed and the address is permanently retired. Future incoming mail is rejected. Retrieval and new sends from the deleted inbox return 404. Other inboxes and the credential remain unchanged. There is no undo or sending-quota refund.
Repeating DELETE is safe and can return 202 or 404. Missing or other-account resources also return 404. The service support inbox hello@cherami.to returns 409 protected_inbox to its owner.
Deletion guide and manual account deletion
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request DELETE \
"https://cherami.to/v1/inboxes/INBOX_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 202
Request accepted; inspect the response for its meaning.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
{
"id": "11111111-1111-4111-8111-111111111111",
"status": "deletion_pending",
"message": "Example"
}HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 403
operation_not_allowed: This account cannot send mail, delete mail, or delete inboxes. Contact support if unexpected.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 404
not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 409
protected_inbox: The service support inbox cannot be deleted.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 500
internal_error: Operation failed; a write may already have happened. Follow the operation-specific recovery below.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: Deleted
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
status | Yes | "deletion_pending" | |
message | Yes | string |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
HTTP conventions, errors and pagination · Download OpenAPI 3.1