How do I create inboxes on any subdomain?

AgentMail can create inboxes on any subdomain of a verified parent domain. You only need to register the parent once instead of adding and verifying every subdomain separately.

For example, registering example.com with subdomains enabled lets you create:

• agent@support.example.com
• sales@west.example.com
• assistant@customer.eu.example.com

How it works

When you enable subdomains, AgentMail adds a wildcard MX record to the domain’s required DNS records. The wildcard routes incoming mail for subdomains to AgentMail. Subdomain inboxes use the parent domain’s sending identity and DKIM configuration.

import os
from agentmail import AgentMail
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
# create the parent domain with subdomains enabled
domain = client.domains.create(
    domain="example.com",
    subdomains_enabled=True,
)

import os
from agentmail import AgentMail
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
# enable subdomains on an existing domain
domain = client.domains.update(
    "example.com",
    subdomains_enabled=True,
)

curl -X PATCH https://api.agentmail.to/v0/domains/example.com \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subdomains_enabled": true}'

# the wildcard record itself
dig +short MX '*.example.com'
# a subdomain without its own records resolves through the wildcard
dig +short MX anything.example.com

import os
from agentmail import AgentMail
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
# create agent@support.example.com
inbox = client.inboxes.create(
    username="agent",
    domain="support.example.com",
)

Important behavior

• The parent domain must be VERIFIED before you create an inbox on one of its subdomains. Otherwise inbox creation returns a 403 error with code domain_not_verified.
• Creating a subdomain inbox without enabling subdomains returns a 422 error.
• Only registered domains appear in the Domains list. Subdomain addresses appear in the Inboxes list.
• Subdomain inboxes share the parent domain’s sending identity, DKIM configuration, and sending reputation.
• Register a subdomain separately if it needs an isolated sending reputation.
• If open tracking is enabled, link.example.com and domains beneath it are reserved for tracking and cannot host inboxes. Creating one returns a 422 error.

Common issues

The parent domain returned to PENDING

This is expected after enabling subdomains. Publish the new wildcard MX record and wait for AgentMail to verify it.

The wildcard MX record is missing

Check whether your DNS provider expects *, *.example.com, or another relative form. Copy the name and value shown by AgentMail whenever possible, then confirm with the dig commands in step 3.

Mail to one subdomain does not arrive while others work

A wildcard record only applies to subdomains that have no DNS records of their own. If the subdomain already has records, such as an A record for a website, add an MX record for that subdomain with the same value as the wildcard. A subdomain with a CNAME record cannot also have an MX record, so use a different subdomain for inboxes.

Inbox creation returns a 422 error

Confirm that subdomains_enabled is true on the parent domain. If tracking is enabled, also confirm that the requested address is not on the reserved link subdomain.

Inbox creation returns a 403 error with code domain_not_verified

The parent domain is not VERIFIED. This is expected right after enabling subdomains: publish the wildcard MX record and wait for verification to finish.

The subdomain is not listed under Domains

This is expected. Only the registered parent is a domain resource. Use the Inboxes list to find addresses created on its subdomains.

For broader domain setup instructions, see Using Custom Domains. If DNS verification is stuck, see Why is my domain not verifying?.