> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://www.agentmail.to/docs/llms.txt.

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

#### 1. Enable subdomains on the parent domain

Enable subdomains when you create the parent domain:

**`Python`**

```python title="Python"
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,
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: process.env.AGENTMAIL_API_KEY });

// create the parent domain with subdomains enabled
const domain = await client.domains.create({
  domain: "example.com",
  subdomainsEnabled: true,
});
```

If the parent domain is already registered, update it instead:

**`Python`**

```python title="Python"
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,
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: process.env.AGENTMAIL_API_KEY });

// enable subdomains on an existing domain
const domain = await client.domains.update("example.com", {
  subdomainsEnabled: true,
});
```

You can also update an existing domain through the API:

**`cURL`**

```bash title="cURL"
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}'
```

> **Warning**
>
> Enabling subdomains on an already verified domain changes its status to `PENDING`. The wildcard MX record is now required, so the domain must be verified again. Existing sending is not interrupted while verification is pending, but you cannot create new inboxes on the domain or its subdomains until it is `VERIFIED` again.

#### 2. Publish the wildcard MX record

The domain response includes the wildcard MX record you need to publish. For a registered domain of `example.com`, it looks like this:

| Field        | Value                                 |
| ------------ | ------------------------------------- |
| Type         | `MX`                                  |
| Name or host | `*`                                   |
| Value        | `inbound-smtp.<region>.amazonaws.com` |
| Priority     | `10`                                  |

The region is `us-east-1` for US organizations and `eu-central-1` for EU organizations (those that call `https://api.agentmail.eu`). Copy the name and value returned for your domain in the AgentMail Console or the API response instead of typing them from this table.

The `*` host represents `*.example.com`. Some DNS providers expect the complete hostname instead. Use the exact name shown in the AgentMail Console or the API response if your provider formats records differently.

> **Note**
>
> If the registered parent is itself a subdomain, such as `mail.example.com`, the wildcard is `*.mail.example.com`. In the `example.com` DNS zone, this is usually entered as `*.mail`.

#### 3. Wait for the parent domain to be verified

AgentMail checks the wildcard MX record with the other required DNS records. Wait until the parent domain returns to `VERIFIED` before creating inboxes on its subdomains.

To check the wildcard record yourself, query it directly and through any subdomain that has no DNS records of its own:

```bash
# 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
```

Both should return the value from the domain response, such as `10 inbound-smtp.us-east-1.amazonaws.com.` for a US organization. An empty result means the record is not published yet or has not propagated.

If the domain remains `PENDING`, open it in the [AgentMail Console](https://console.agentmail.to) and confirm that the wildcard MX record is valid. DNS changes may take time to propagate.

#### 4. Create an inbox on a subdomain

Pass the complete subdomain in the inbox's `domain` field:

**`Python`**

```python title="Python"
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",
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: process.env.AGENTMAIL_API_KEY });

// create agent@support.example.com
const inbox = await client.inboxes.create({
  username: "agent",
  domain: "support.example.com",
});
```

You do not need to register `support.example.com` as another domain. AgentMail authorizes it through the verified parent domain.

## 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](https://docs.agentmail.to/custom-domains). If DNS verification is stuck, see [Why is my domain not verifying?](https://docs.agentmail.to/knowledge-base/domain-not-verifying).