Skip to navigation
Getting Started

How do I create my first inbox?

Get up and running with your first AgentMail inbox.

An inbox gives your AI agent its own email address. You can create one on the shared @agentmail.to domain right away, or on your own domain once it is verified. For the full path from sign-up to your first sent email, follow the Quickstart.

Install the SDK

pip install agentmail

The examples below read your API key from the AGENTMAIL_API_KEY environment variable. Keep the key out of your source code. See How do I get my API key? to create one.

Create an inbox

With no arguments, AgentMail picks a random username on @agentmail.to:

import os
from agentmail import AgentMail
client = AgentMail(api_key=os.environ["AGENTMAIL_API_KEY"])
# create an inbox with a random address on agentmail.to
inbox = client.inboxes.create()
print(f"Inbox created: {inbox.email}")

email is the new address, such as cleverstar482@agentmail.to. Pass inbox_id (inboxId in TypeScript) to every other call on the inbox. The inbox can receive mail as soon as it exists.

Choose the address and make creation safe to retry

The main fields, all optional:

FieldWhat it does
usernameThe part before the @. Random if you leave it out.
domainDefaults to agentmail.to. Can be one of your verified domains, or a subdomain of a verified domain that has subdomains enabled.
display_nameThe sender name recipients see. If you leave it out, the display name is AgentMail.
client_idYour own ID for this inbox. Calling create again with the same client_id returns the inbox it created the first time instead of creating another one.
metadataYour own key-value data, such as a user or tenant ID. See Metadata.

Use client_id whenever your agent creates its inbox on startup, so a restart or a retried request does not create a second inbox:

import os
from agentmail import AgentMail
from agentmail.inboxes import CreateInboxRequest
client = AgentMail(api_key=os.environ["AGENTMAIL_API_KEY"])
# safe to run on every startup: the same client_id returns the same inbox
inbox = client.inboxes.create(
    request=CreateInboxRequest(
        username="acme-support-agent",
        display_name="Acme Support",
        client_id="acme-support-agent-v1",
    )
)
# send your first email
client.inboxes.messages.send(
    inbox.inbox_id,
    to=["you@example.com"],
    subject="Hello from my agent",
    text="This is a plain text version.",
    html="<p>This is an <strong>HTML</strong> version.</p>",
)

Send both text and html so the message reads well in every email client. To create inboxes on your own domain, set domain to a domain you have added and verified. Custom domains are available on the Developer plan and above; see How do I set up a custom domain?.

Common issues

ErrorWhat it meansWhat to do
403 resource_takenThe address is not available to your organization, usually because another AgentMail user already has that username on agentmail.to.Choose a different username. When the error includes a suggestions field, it lists usernames that are currently available.
403 already_existsYour organization already has an inbox with this address.Fetch the existing inbox. If you created it with a client_id, calling create with that same client_id returns it instead of this error.
403 limit_exceededYour organization has as many inboxes as its plan allows. The Free plan includes 3. An agent that signed itself up has 1 until its human verifies it or claims the inbox, which moves it to the Free plan.Delete an inbox you no longer need, or upgrade your plan. A self-signed-up agent should complete verification instead; the error’s fix field explains how.
404 not_foundThe domain has not been added to your organization, or is outside your API key’s scope.Add the domain first. See How do I set up a custom domain?.
403 domain_not_verifiedThe domain is added but its DNS records have not been verified yet.Add the DNS records AgentMail returns for the domain, then verify it. See Why is my domain not verifying?.
422 unprocessable, “does not have subdomains enabled”domain is a subdomain of a domain you added, and that domain does not have subdomains enabled.Enable subdomains on the parent domain, publish the wildcard MX record it then lists, and wait for the domain to verify again. Or add the subdomain as a domain of its own. See How do I create inboxes on any subdomain?.
Duplicate inboxes after restartsWithout a username, every create call makes a new inbox with a random address.Pass a stable client_id, as in the example above.

Most error responses also carry a fix field with the next step. See the Error Reference for all error codes.

Next steps