# Accounts, inboxes, and messages

What one account holds, what every connection to it reaches, and how inboxes, messages, threads and labels fit together.

Source: https://cherami.to/docs/concepts



## One account, several ways to connect [#one-account-several-ways-to-connect]

One Cherami account holds your inboxes and mail. The HTTP API, remote MCP and the Cherami plugin all reach that same account; they are ways in, not separate mailboxes.

An **API key** authenticates HTTP and SDK requests, or an MCP client configured with a key. You create one in [Account → API keys](https://cherami.to/account/api-keys), or [approve an agent](https://cherami.to/docs/quickstart#ask-your-human-for-approval) from the Account home so it gets its own key without one passing through chat. Either way the key is shown once.

An **OAuth connection** is for MCP clients that sign in through your browser: you approve access there, and no key reaches the agent. The plugin connects this way.

Every key and connection reaches every inbox on the account and shares its sending allowance. Giving each agent its own key and inbox keeps work organized, not isolated ([sharing an account](https://cherami.to/docs/guides/multi-agent)).

### Team and application access [#team-and-application-access]

An account has one owner. If you need several owners, organization management, keys limited to particular inboxes, or single sign-on (SSO), email [hello@cherami.to](mailto:hello@cherami.to) and tell us how your team or application needs access to work.

## Inboxes are email addresses [#inboxes-are-email-addresses]

An **inbox** has an address, such as `hello@cherami.to`, and an ID you use in API requests. It holds the mail its address receives, its drafts and copies of what it sends. Its address and mail stay available across agent sessions, so it suits ongoing correspondence.

`name` is an optional name for your own reference; `sender_name` is the From name on mail the inbox sends. You can change either. The address can't change: to move to a new one, follow [Change your agent's email address](https://cherami.to/docs/guides/change-email-address). Your sign-in email is how we contact you; it isn't an agent inbox.

Deleting an inbox permanently removes its mail and retires its address: nobody can use it again, and mail sent to it no longer arrives. See [inbox operations](https://cherami.to/docs/api/inboxes).

### Choose an inbox before creating one [#choose-an-inbox-before-creating-one]

List the account's inboxes and use the one that already belongs to the work: an earlier session or another agent may have it, with its history. Create one when the work needs its own address, such as a new project, a correspondent who should write somewhere dedicated, or a [planned address change](https://cherami.to/docs/guides/change-email-address). An account starts with room for two inboxes (`inbox_limit` in the list response) and addresses are permanent, so agree the prefix with whoever owns the account, then [create the inbox](https://cherami.to/docs/api/inboxes/create-inbox) and share the address it returns.

### Use your own domain [#use-your-own-domain]

Every address ends in `@cherami.to`. If you need addresses on a domain you own, email [hello@cherami.to](mailto:hello@cherami.to) and tell us how you'd use them.

## Received and sent messages are different resources [#received-and-sent-messages-are-different-resources]

A **received message** is mail delivered to one of your inboxes. It's listed as soon as it arrives; its body and attachments are readable once `processing_status` is `ready`. For `failed`, the raw message is still available ([waiting for content](https://cherami.to/docs/guides/receiving#wait-for-content-not-just-receipt)).

A **draft** is an email saved without sending. It can be incomplete, and any session on the account can pick it up to revise or discuss. Sending freezes it into one outgoing attempt. See [saved drafts](https://cherami.to/docs/guides/drafts).

A **sent message** is one outgoing attempt and what it contained. Its status is `accepted`, `rejected` or `unknown`; `accepted` means the provider took it, not that it was delivered. The [sending guide](https://cherami.to/docs/guides/sending) explains outcomes and recovery.

Requests identify mail by Cherami IDs, such as a message's `id`, never by the email's own Message-ID header. To reply, use the `id` of a ready received message or an accepted sent message in the same inbox. [Reply operations](https://cherami.to/docs/guides/sending#reply-to-a-message) fill in the recipients and subject; an explicit send lets you set them yourself.

## Webhooks tell your code when to look [#webhooks-tell-your-code-when-to-look]

A **webhook** is an https URL of yours that we call when received mail is ready or a send is accepted. It carries identifiers only; fetch the message through the API. See [webhook notifications](https://cherami.to/docs/guides/webhooks).

## Threads give context; labels organize copies [#threads-give-context-labels-organize-copies]

A **thread** is a conversation in one inbox: the received and sent messages that reply to each other. We group them automatically by their reply headers, not by matching subjects. To reply, pick a message in the thread; the thread itself isn't a reply target. See [conversation threads](https://cherami.to/docs/guides/conversations).

A **label** is a case-sensitive tag on a received or sent message, shared by everyone on the account. Use labels to track your own workflow and filter mail. Labeling a thread tags the messages in it now; later replies don't get those labels. See [organizing with labels](https://cherami.to/docs/guides/labels).

Ready to connect? Choose the [HTTP quickstart](https://cherami.to/docs/quickstart), [remote MCP](https://cherami.to/docs/mcp) or the [Cherami plugin](https://cherami.to/docs/plugin).
