Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Custom email domains
description: Send and receive Inkbox email from a domain you own

---


# Custom email domains

Use a domain you already own as the From and To address for your agents' email. Setup is three steps and a short DNS wait.

## Why bring your own domain?

- **Recognizable sender.** Recipients see your brand.
- **Your own deliverability reputation**, separate from a shared sending pool.
- **Many agent mailboxes per domain.** Run a fleet of agents under one identity.

## Apex or subdomain?

You can register either an apex domain (`yourdomain.com`) or a subdomain (`agents.yourdomain.com`).

**A subdomain is the safer default.** It does not touch the apex's existing mail setup, will not displace any inbox you already use for human email, and is easy to undo.

**Use the apex** only if you are not currently using it for email, or if you are moving the whole domain over to Inkbox.

## Before you start

You will need:

- A domain you own, with the ability to edit its DNS records at your registrar.
- An Inkbox API key, or access to the [Inkbox Console](https://inkbox.ai/console/).
- A few minutes of hands-on time.

## Step 1: Register the domain with Inkbox

You can register a domain from the Console or directly through the API.

### Console

1. Open [inkbox.ai/console](https://inkbox.ai/console/) and go to the Domains section.
2. Click **Add domain** and enter the bare domain (no `https://`, no path, no trailing slash).
3. The Console shows the list of DNS records you need to publish at your registrar. Leave the page open; you will come back to it in [Step 2](#step-2-add-the-dns-records-at-your-registrar).

### API

Domain registration, DNS-record retrieval, verification, DKIM rotation, and deletion are available via the Console and the REST API only. The SDKs and CLI cover `list` and `set-default`.

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/domains/" \\
    -H "X-API-Key: YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{"domain": "agents.yourdomain.com"}'
```

The response includes the domain object and a `dns_records` array. Each record has a `type`, `host`, and `value`. Copy them into your DNS provider exactly as returned; treat them as opaque strings.

### Apex with existing MX records

If the apex you're registering already has MX records, the request returns `422` with an `apex_mx_warning`. To displace the existing mail provider, re-send with `apex_mx_acknowledged: true`. Otherwise, register a subdomain instead.

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/domains/" \\
    -H "X-API-Key: YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{"domain": "yourdomain.com", "apex_mx_acknowledged": true}'
```

### SPF lookup warning

If the response includes an `spf_lookup_report` near the [RFC 7208](https://datatracker.ietf.org/doc/html/rfc7208) 10-lookup limit, flatten or remove unused includes from your existing SPF before mail will authenticate.

## Step 2: Add the DNS records at your registrar

These records do two things: they route mail addressed to your domain to Inkbox, and they let recipients verify outbound mail really came from you (so it doesn't get flagged as spam). You're not touching anything else about how your domain works.

Open the DNS settings for your domain at your registrar, and add each record from the previous step exactly as the API returned it.

### Provider-specific guides

These are the official "add DNS records" guides for the most common registrars:

| Registrar | Guide |
| --- | --- |
| Cloudflare | [Manage DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/) |
| AWS Route 53 | [Creating records by using the Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html) |
| Vercel | [Managing DNS Records](https://vercel.com/docs/domains/managing-dns-records) |
| Porkbun | [How to Add DNS Records on Porkbun](https://kb.porkbun.com/article/231-how-to-add-dns-records-on-porkbun) |
| Namecheap | [How do I set up host records for a domain?](https://www.namecheap.com/support/knowledgebase/article.aspx/434/2237/how-do-i-set-up-host-records-for-a-domain/) |
| Squarespace Domains | [Adding DNS records to your domain](https://support.squarespace.com/hc/en-us/articles/360002101888-Adding-DNS-records-to-your-domain) |
| GoDaddy | [Manage DNS records](https://www.godaddy.com/help/manage-dns-records-680) |

### Generic walkthrough

If your registrar isn't listed, the steps are essentially the same everywhere:

1. Open the DNS settings page for the domain at your registrar.
2. For each record from Inkbox, add a new record with the matching **Type**, **Host** (sometimes called **Name**), and **Value** (sometimes called **Content** or **Target**).
3. Leave the **TTL** at the default.
4. Save.

<WarningNotice title="Long DKIM TXT values">
DKIM TXT records can exceed 255 characters. Most registrars handle long values automatically, but a few require splitting the value into multiple quoted segments on the same record. If your DKIM record is rejected by the registrar, paste the value into a tool that splits it into 255-char chunks separated by spaces (not newlines), keeping each chunk in its own pair of quotes.
</WarningNotice>

## Step 3: Verify

Verification is automatic once the records are in place. To trigger an immediate re-check (instead of waiting for the next polling cycle), click **Re-check verification** in the [Console](https://inkbox.ai/console/domains), or call:

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/domains/{domain_id}/verify" \\
    -H "X-API-Key: YOUR_API_KEY"
```

### What the status values mean

| Status | What it means |
| --- | --- |
| `awaiting_ownership` | We are waiting to see your ownership TXT record. |
| `pending` | Ownership is confirmed; we are waiting for the rest of the records to propagate. |
| `verifying` | Records are visible; final checks are running. |
| `verified` | Healthy. You can send and receive mail on the domain. |
| `dns_invalid` | One or more records are present but their values don't match what was issued. |
| `failed` | A 72-hour window elapsed without success. Delete the domain and start over. |
| `degraded` | The domain was previously verified, but a record has since been edited or removed. |
| `pending_deletion` | The domain is in its 24-hour delete grace period and can still be restored. |

Most domains reach `verified` within a few minutes. More than 24 hours almost always means something is wrong with a record value at your registrar; see [Troubleshooting](#troubleshooting).

## Using your domain

Once your domain is `verified`, create mailboxes on it like any other Inkbox domain ([Mail API: Mailboxes](/docs/api/mail/mailboxes)).

**Python**

```python
with Inkbox(api_key="YOUR_API_KEY") as inkbox:
    identity = inkbox.create_identity(
        "research-assistant",
        sending_domain="agents.yourdomain.com",
    )
    identity.send_email(
        to=["jane@example.com"],
        subject="Hello from your custom domain",
        body_text="This message was sent from your own domain.",
    )
```

**TypeScript**

```javascript
await inkbox.messages.send(
    "research-assistant@agents.yourdomain.com",
    {
        to: ["jane@example.com"],
        subject: "Hello from your custom domain",
        bodyText: "This message was sent from your own domain.",
    },
);
```

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/mailboxes/research-assistant@agents.yourdomain.com/messages" \\
    -H "X-API-Key: YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
        "recipients": {"to": ["jane@example.com"]},
        "subject": "Hello from your custom domain",
        "body_text": "This message was sent from your own domain."
    }'
```

Inbound mail flows through the same pipeline as default mailboxes, including [webhooks](/docs/api/mail/webhooks). A `dmarc-reports@yourdomain.com` mailbox is auto-provisioned to receive DMARC aggregate reports.

## Managing your domain

### List your domains

**Python**

```python
with Inkbox(api_key="YOUR_API_KEY") as inkbox:
    for d in inkbox.domains.list():
        print(d.domain, d.status, d.is_default)
```

**TypeScript**

```javascript
const domains = await inkbox.domains.list();
for (const d of domains) {
    console.log(d.domain, d.status, d.isDefault);
}
```

**cURL**

```bash
curl -X GET "https://inkbox.ai/api/v1/domains/" \\
    -H "X-API-Key: YOUR_API_KEY"
```

**CLI**

```bash
inkbox domain list
```

Pass a `status` filter (e.g. `status="verified"`) to narrow the result.

### Set as default

A verified domain can be set as your organization's default. New mailboxes will use it automatically. To revert, call `set-default` with `inkboxmail.com`. Requires an **admin-scoped API key**; non-admin keys receive `403`.

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/domains/agents.yourdomain.com/set-default" \\
    -H "X-API-Key: YOUR_API_KEY"
```

**Python**

```python
with Inkbox(api_key="YOUR_API_KEY") as inkbox:
    inkbox.domains.set_default("agents.yourdomain.com")
```

**TypeScript**

```javascript
await inkbox.domains.setDefault("agents.yourdomain.com");
```

**CLI**

```bash
inkbox domain set-default agents.yourdomain.com
```

### Rotate DKIM

You can rotate at any time. Sending isn't interrupted: the old key stays active until the new TXT is published and verified.

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/domains/{domain_id}/rotate-dkim" \\
    -H "X-API-Key: YOUR_API_KEY"
```

### Delete

Deletion enters a 24-hour grace period (sending and receiving stop, but the domain can be restored). After 24h it's permanent. If the domain has mailboxes, the API returns blockers; remove them first.

**Delete**

```bash
curl -X DELETE "https://inkbox.ai/api/v1/domains/{domain_id}" \\
    -H "X-API-Key: YOUR_API_KEY"
```

**Restore**

```bash
curl -X POST "https://inkbox.ai/api/v1/domains/{domain_id}/restore" \\
    -H "X-API-Key: YOUR_API_KEY"
```

## Troubleshooting

<Accordion title={<>My domain is stuck on <code>awaiting_ownership</code> or <code>pending</code></>}>

Most often, the ownership or DKIM TXT record hasn't propagated yet, or there's a typo in the value.

1. Run `dig TXT <host>` against the exact host returned by the API. If the value isn't returned, the record hasn't published yet at your registrar.
2. Open the record at your registrar and compare the value byte-for-byte to what the API returned. Common causes: leading or trailing whitespace, a stray quote character, or a missing semicolon.
3. Click **Re-check verification** in the [Console](https://inkbox.ai/console/domains), or call `POST /api/v1/domains/{id}/verify`.

</Accordion>

<Accordion title={<>The status is <code>dns_invalid</code> after I added the records</>}>

The record is at the host but its value doesn't match. Usually:

- Surrounding quotes were re-quoted by the registrar, producing a doubly-quoted value.
- A long DKIM value was split with newlines or extra spaces between segments.
- The wrong value was copied (e.g. a key from a previous DKIM rotation).

Compare `dig TXT <host>` against the value in the Console and re-publish.

</Accordion>

<Accordion title={`I'm seeing a "Too many SPF records" error`}>

A domain can only have **one** SPF TXT record. If you already have one for another sender, merge Inkbox into it instead of adding a second SPF record.

Before:

```
v=spf1 include:_spf.example-other-sender.com ~all
```

After:

```
v=spf1 include:_spf.example-other-sender.com include:spf.inkbox.ai ~all
```

If your existing SPF is close to the 10-lookup limit, you may also need to flatten or remove unused includes.

</Accordion>

<Accordion title="My DKIM record won't validate">

DKIM values are long and some registrars mangle them. If `dig TXT <host>` returns a truncated value, re-paste using the registrar's long-TXT or raw mode, or split the value into 255-char quoted segments separated by single spaces (no newlines).

</Accordion>

<Accordion title="Apex registration was rejected with a warning">

Your apex already has MX records. Re-send with `apex_mx_acknowledged: true` to displace the existing mail provider, or register a subdomain instead (e.g. `agents.yourdomain.com`).

</Accordion>

<Accordion title={<>The domain was <code>verified</code> and is now <code>degraded</code></>}>

A record at your registrar was edited, removed, or dropped during a bulk import. Open the domain in the [Console](https://inkbox.ai/console/domains), compare each record to what's published, re-publish anything that doesn't match, then click **Re-check verification**.

</Accordion>

## FAQs

<Accordion title="Should I use a subdomain or the apex?">

A subdomain in nearly all cases. See [Apex or subdomain?](#apex-or-subdomain).

</Accordion>

<Accordion title="Do you re-check DNS after a domain is verified?">

Yes. If a record is later removed or changed, the domain transitions to `degraded` and the [Console](https://inkbox.ai/console/domains) flags it.

</Accordion>

<Accordion title="Can I rotate DKIM at any time?">

Yes. Sending is not interrupted during rotation. The old key stays active until the new TXT record is published and verified.

</Accordion>

<Accordion title="Can multiple Inkbox organizations share one domain?">

No. A registered domain belongs to one organization at a time.

</Accordion>