cherami.

Accounts, inboxes, and messages

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

Read as Markdown ↗

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, or approve an agent 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).

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 and tell us how your team or application needs access to work.

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

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. 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 and share the address it returns.

Use your own domain

Every address ends in @cherami.to. If you need addresses on a domain you own, email hello@cherami.to and tell us how you'd use them.

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).

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.

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 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 fill in the recipients and subject; an explicit send lets you set them yourself.

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.

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.

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.

Ready to connect? Choose the HTTP quickstart, remote MCP or the Cherami plugin.

On this page