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.

Each custom domain costs $4/month — see pricing. The charge starts when the domain first verifies (you pay nothing during DNS setup) and stops when you delete the domain.

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 admin-scoped API key, or access to the Inkbox 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

Open inkbox.ai/console and go to the Domains section.
Click Add domain and enter the bare domain (no https://, no path, no trailing slash).
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.

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

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

Long DKIM TXT valuesDKIM 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.

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, or call:

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.

Using your domain

Once your domain is verified, create mailboxes on it like any other Inkbox domain (Mail API: Mailboxes).

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

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 -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. A dmarc-reports@yourdomain.com mailbox is auto-provisioned to receive DMARC aggregate reports.

Managing your domain

List your domains

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

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

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

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 -X POST "https://inkbox.ai/api/v1/domains/agents.yourdomain.com/set-default" \
  -H "X-API-Key: YOUR_API_KEY"

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

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

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

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

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

Troubleshooting

My domain is stuck on awaiting_ownership or pending

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

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.
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.
Click Re-check verification in the Console, or call POST /api/v1/domains/{id}/verify.

The status is dns_invalid 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.

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.

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

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

The domain was verified and is now degraded

A record at your registrar was edited, removed, or dropped during a bulk import. Open the domain in the Console, compare each record to what’s published, re-publish anything that doesn’t match, then click Re-check verification.

FAQs

Should I use a subdomain or the apex?

A subdomain in nearly all cases. See Apex or subdomain?.

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

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.

Get started

Capabilities

API keys

MCP

Webhooks

Signing keys

Skills

Integrations

Custom email domains

Why bring your own domain?

Apex or subdomain?

Before you start

Step 1: Register the domain with Inkbox

Console

API

Apex with existing MX records

SPF lookup warning

Step 2: Add the DNS records at your registrar

Step 3: Verify

What the status values mean

Using your domain

Managing your domain

List your domains

Set as default

Rotate DKIM

Delete

Troubleshooting

FAQs

​Why bring your own domain?

​Apex or subdomain?

​Before you start

​Step 1: Register the domain with Inkbox

​Console

​API

​Apex with existing MX records

​SPF lookup warning

​Step 2: Add the DNS records at your registrar

​Step 3: Verify

​What the status values mean

​Using your domain

​Managing your domain

​List your domains

​Set as default

​Rotate DKIM

​Delete

​Troubleshooting

​FAQs

Why bring your own domain?

Apex or subdomain?

Before you start

Step 1: Register the domain with Inkbox

Console

API

Apex with existing MX records

SPF lookup warning

Step 2: Add the DNS records at your registrar

Step 3: Verify

What the status values mean

Using your domain

Managing your domain

List your domains

Set as default

Rotate DKIM

Delete

Troubleshooting

FAQs