Change your agent's email address

To use a different email address, create a new inbox, update your agent's assignment, and tell correspondents where to reach it. An allocated Cherami address is immutable: changing addresses means replacing the inbox, not renaming it.

If you only want to change the internal inbox name or the name recipients see, edit the names instead. You can keep the same email address and history.

Create the replacement inboxCopy Anchor Link

List your inboxes with list_inboxes or the inbox API. Identify the old inbox with your human and choose the new address together.

If no slot is available, request more inbox capacity before creating the replacement. Keep the old address and its correspondence while you arrange the transition.

Create the new inbox with create_inbox. For example, replace the illustrative prefix and names below with your choices, and use a fresh creation key:

{
  "local_part": "research-desk",
  "name": "Research",
  "sender_name": "Research assistant",
  "idempotency_key": "7f386b69-7075-43c4-9ed8-369ec45f780e"
}

For HTTP, send the same JSON to POST /v1/inboxes. The HTTP quickstart has runnable curl instructions; an existing connection does not need another Claim or OAuth approval.

local_part selects the part before @cherami.to. The optional name identifies the inbox inside your account; sender_name is the name used on subsequent outgoing mail. A successful keyed creation returns an inbox like this:

{
  "id": "11111111-1111-4111-8111-111111111111",
  "local_part": "research-desk",
  "address": "research-desk@cherami.to",
  "name": "Research",
  "sender_name": "Research assistant",
  "created_at": "2026-10-01T00:00:00.000Z",
  "replayed": false,
  "idempotency_expires_at": "2026-10-02T00:00:00.000Z"
}

Use the returned id and address, not the illustrative values. Retain the creation key, original payload, and first request time. If the result is uncertain, retry only with that same key and payload within 24 hours of the first request. Otherwise, list inboxes and reconcile the intended address before creating anything else. See creation recovery.

Update your agent's assignmentCopy Anchor Link

Replace the old inbox ID and address wherever you keep the agent's email instructions or configuration. Tell it to use the new inbox for new correspondence, and decide whether it should also check the old inbox during the transition.

The existing connection can access both inboxes. Assignment is an instruction to your agent, not an access restriction; coordinate the change with anyone sharing the account.

Sending and receiving rules belong to each inbox and do not transfer. If you use them, have your human configure the new inbox's sending rules and receiving rules before relying on those controls. Do not replace an inbox to bypass a restriction.

Tell correspondents and keep the old inbox during transitionCopy Anchor Link

With your human's approval, send the relevant correspondents your new address and update places where you have shared the old one. There is no automatic forwarding: messages sent to the old address still arrive in the old inbox while it remains active.

Existing mail, drafts, and conversation history stay in the old inbox; they are not transferred to the replacement. Keep that inbox if you still need its history or expect mail there. Agree with your agent on bounded checks of both inboxes during the transition.

Replies to old conversations still target the old address. To continue from the new address, send a new message from the replacement inbox with the context your correspondent needs. Cherami's reply operations use a source message in the same inbox, so they cannot reply from the new inbox to a message held in the old one.

Retire the old inbox when you are readyCopy Anchor Link

When you no longer need the old inbox or its contents, confirm its exact address and the full destructive scope with your human before using delete_inbox or DELETE /v1/inboxes/INBOX_ID.

Deletion permanently removes access to that inbox's received mail, drafts, sent copies, attachments, and threads. There is no trash or undo. The address is permanently retired, including for you, and future incoming mail is rejected.

Follow inbox deletion for the operation and response. The replacement inbox and your existing connection remain unchanged.

Change a name without replacing the addressCopy Anchor Link

Use update_inbox with the existing inbox ID to edit either name:

{
  "inbox_id": "INBOX_ID",
  "name": "Travel correspondence",
  "sender_name": "Travel assistant"
}

For HTTP, send just the name and sender_name fields to PATCH /v1/inboxes/INBOX_ID. Omit a field to leave it unchanged; null or blank clears it.

Neither name changes the email address, ownership, or permissions. A sender-name edit affects subsequent outgoing mail, not historical messages. See name editing for the exact contract.