Testing email on your own domain

Shared disposable domains are fine for testing your own signup flow. They stop being fine the moment the thing you are testing cares who you are:

• A B2B product that only accepts a corporate address, not a throwaway one.
• A staging environment behind an allowlist of company domains.
• A deliverability check that is only meaningful on the domain you actually send to.
• A demo where alex@acme-demo.com is the point, and k7f2p9@mail.inboxdome.com is not.

For those, bring your own domain: you own it, we receive on it, and the inboxes look like ordinary addresses on your brand.

1. Claim the domain

curl -X POST https://inboxdome.com/v1/domains \
  -H "Authorization: Bearer $INBOXDOME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.acme-demo.com"}'

The response tells you exactly what to publish:

{
  "domain": { "domain": "mail.acme-demo.com", "status": "pending", "verified": false },
  "verification": {
    "type": "TXT",
    "name": "_inboxdome.mail.acme-demo.com",
    "value": "inboxdome-verify=3f9c…"
  }
}

Use a subdomain you are willing to dedicate to receiving (mail., test., inbox.), not your apex. The apex is where your real MX records live, and you do not want a test harness anywhere near them.

Only an admin key can manage domains; a member key gets a 403. Ten custom domains per account.

2. Publish the TXT record and verify

Add the TXT record at your DNS provider, then:

curl -X POST https://inboxdome.com/v1/domains/mail.acme-demo.com/verify \
  -H "Authorization: Bearer $INBOXDOME_KEY"

We resolve _inboxdome.<domain> over DNS-over-HTTPS and look for the exact token. If it is not there yet you get a txt_not_found back. That is almost always propagation, not a mistake. Wait and call verify again; it is safe to retry.

Proving ownership this way means nobody can claim a domain they do not control, which is the whole reason the step exists.

3. Routing the mail (this part needs a nameserver change)

Being straight with you about where the automation stops.

Verification is automatic, and so is everything after it. The one step we cannot do for you is repointing the domain: receiving mail requires its DNS to run through our Cloudflare account, so the verify call hands back two nameservers to set at your registrar.

{
  "domain": { "domain": "mail.yourapp.com", "verified": true },
  "nameservers": ["kipp.ns.cloudflare.com", "opal.ns.cloudflare.com"]
}

Once that delegation resolves we enable mail routing and activate the domain by ourselves. We check every 15 minutes, so in practice it is live shortly after your registrar propagates. If you cannot delegate the apex, use a subdomain you can.

Until it is activated the domain sits in pending, and inboxes created on it will not receive. Check where a domain has got to with:

curl https://inboxdome.com/v1/domains/custom \
  -H "Authorization: Bearer $INBOXDOME_KEY"

We would rather tell you that up front than have you discover it while debugging a test that was never going to pass. It is the next thing we are automating.

4. Use it

Once the domain is active, name it when you create an inbox:

const inbox = await client.createInbox({
  domain: 'mail.acme-demo.com',
  localPart: 'alex',
});
// alex@mail.acme-demo.com

Everything else is unchanged: waitForOtp, assertEmail, webhooks all behave exactly as they do on a shared domain.

Isolation, and what your domain does not join

A custom domain belongs to your account. It never enters the pool the public site picks from, so a stranger on inboxdome.com cannot land on your brand’s domain, and nobody outside your account can create an inbox on it or read one.

When you are done with it

Deleting the domain from InboxDome stops us receiving for it. Also remove the mail routing from your DNS. A domain still pointing MX at a service that is no longer expecting it is a quiet way to lose mail. The verification TXT record can go at the same time.

See also: WordPress and WooCommerce · API reference · Testing email webhooks