Guides

# Domain Setup

Before you can send any email, you need at least one verified sending domain. This guide walks through the complete setup — from creating the domain record to confirming DNS verification.

## Overview

1

Create a domain record

Provide your domain name — the response returns all DNS values.

2

Add DNS records

Records are pushed automatically if a DNS integration is configured, otherwise add them manually at your provider.

3

Verify

Mission Inbox checks that the records have propagated correctly.

DNS propagation can take up to 48 hours depending on your provider and TTL settings. The verify endpoint tells you exactly which records are missing so you know what to fix.

## Step 1 — Create the Domain

Call `POST /api/domains/create` with your domain name. Optionally pass a `projectId` to group the domain under a project. The response returns all DNS record values you need for the next step.

cURL

```bash
curl -X POST "https://api.v4.missioninbox.com/api/domains/create" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b" \
  -H "Content-Type: application/json" \
  -d '{
    "domainName": "example.com",
    "projectId": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

Response

```json
{
  "uuid": "86c0c812-cb50-4b25-8b01-721e3933bf63",
  "domainName": "example.com",
  "verified": false,
  "verificationToken": "uFfAONu1UBFgR1qNgXJOOb2bIHlQTlLd",
  "dnsVerificationString": "postal-verification uFfAONu1UBFgR1qNgXJOOb2bIHlQTlLd",
  "spfHost": "example.com",
  "spfValue": "v=spf1 include:spf.cobalt.obmengine.com ~all",
  "dkimHost": "mi-tAsUUQ._domainkey.example.com",
  "dkimValue": "v=DKIM1; t=s; h=sha256; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCdJ03e...",
  "mxHost": "example.com",
  "mxValue": "staging.outboxment.com",
  "mxPriority": 10,
  "dmarcHost": "_dmarc.example.com",
  "dmarcValue": "v=DMARC1; p=quarantine; rua=mailto:abuse@example.com; ruf=mailto:abuse@example.com; sp=quarantine; adkim=r; aspf=r; fo=1; ri=864000;",
  "hasDnsManager": false
}
```

## Step 2 — Add DNS Records

If your organisation has a [DNS provider key](https://doc.v4.missioninbox.com/sales/api/dns-credentials.md) connected for the domain's DNS host, the records were already pushed when the domain was created (check `emailDns.pushed` in the create response). To push them again, or for a domain added before the key was connected, call `POST /api/domains/push-dns`. The `results` array in the response confirms per-record success or failure.

Without a connected key, copy each `name` / `value` pair from the `dnsRecords` array into your DNS provider manually. All five records are required.

cURL

```bash
curl -X POST "https://api.v4.missioninbox.com/api/domains/push-dns" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b" \
  -H "Content-Type: application/json" \
  -d '{
    "domainName": "yourdomain.com"
  }'
```

Response — DNS records

```json
{
  "domainName": "example.com",
  "message": "Successfully pushed 5 DNS records for example.com via CloudFlare.",
  "dnsRecords": [
    { "type": "TXT",   "name": "example.com",                      "value": "v=spf1 include:spf.cobalt.obmengine.com ~all",  "purpose": "spf" },
    { "type": "TXT",   "name": "mi-tAsUUQ._domainkey.example.com", "shortName": "mi-tAsUUQ._domainkey", "value": "v=DKIM1; t=s; h=sha256; p=...", "purpose": "dkim" },
    { "type": "CNAME", "name": "bounce.example.com",               "shortName": "bounce", "value": "rp.cobalt.obmengine.com",        "purpose": "return_path" },
    { "type": "MX",    "name": "example.com",                      "value": "staging.outboxment.com", "priority": 10,         "purpose": "mx" },
    { "type": "TXT",   "name": "_dmarc.example.com",               "value": "v=DMARC1; p=quarantine; rua=mailto:abuse@example.com; ...", "purpose": "dmarc" }
  ],
  "results": [
    { "record": { "type": "TXT",   "name": "example.com",                      "purpose": "spf"         }, "success": true },
    { "record": { "type": "TXT",   "name": "mi-tAsUUQ._domainkey.example.com", "purpose": "dkim"        }, "success": true },
    { "record": { "type": "CNAME", "name": "bounce.example.com",               "purpose": "return_path" }, "success": true },
    { "record": { "type": "MX",    "name": "example.com",                      "purpose": "mx"          }, "success": true },
    { "record": { "type": "TXT",   "name": "_dmarc.example.com",               "purpose": "dmarc"       }, "success": true }
  ]
}
```

| Record              | Purpose                                                                    | Required |
| ------------------- | -------------------------------------------------------------------------- | -------- |
| SPF (TXT)           | Authorises Mission Inbox servers to send on behalf of your domain.         | Required |
| DKIM (TXT)          | Cryptographic signature proving the email wasn't modified in transit.      | Required |
| Return Path (CNAME) | Aligns bounce handling with your sending domain to improve deliverability. | Required |
| MX                  | Required for warmup — the warmup network delivers reply emails here.       | Required |
| DMARC (TXT)         | Policy record that instructs receivers how to handle failed SPF/DKIM.      | Required |

## Step 3 — Verify Your Domain

Once the records are in place, call verify. The API checks each record individually and returns a per-record pass/fail. Re-call as many times as you need — it's safe to poll every few minutes until all checks pass.

cURL

```bash
curl -X POST "https://api.v4.missioninbox.com/api/domains/verify" \
  -H "X-Server-API-Key: miacme_4eC8vKmN2pQrStUwXyZaB6dEfGhIjLoPqRsT9uVwX1b" \
  -H "Content-Type: application/json" \
  -d '{
    "domainName": "yourdomain.com"
  }'
```

Response — verified

```json
{
  "message": "Domain example.com verified successfully",
  "dnsChecks": {
    "spf":         { "status": "OK", "error": null },
    "dkim":        { "status": "OK", "error": null },
    "return_path": { "status": "OK", "error": null },
    "mx":          { "status": "OK", "error": null },
    "dmarc":       { "status": "OK", "error": null }
  },
  "fullyVerified": true
}
```

Response — failed

```json
{
  "message": "We couldn't verify your domain. Please double check you've added the TXT record correctly.",
  "dnsChecks": {
    "spf":         { "status": "Missing", "error": "No SPF record exists for this domain" },
    "dkim":        { "status": "Missing", "error": "No DKIM record exists for this domain" },
    "return_path": { "status": "Missing", "error": "There is no return path record at bounce.example.com" },
    "mx":          { "status": "Missing", "error": "No MX record exists for this domain" },
    "dmarc":       { "status": "Missing", "error": "No DMARC record exists for this domain" }
  },
  "fullyVerified": false
}
```

## Troubleshooting

DKIM record not found

TXT records can take longer to propagate. Wait 30 minutes and retry. The DKIM host includes a unique selector prefix (e.g. mi-tAsUUQ.\_domainkey.yourdomain.com) — use the exact dkimHost value returned by the API.

SPF check fails after adding the record

A domain can only have one SPF TXT record. If you already have one, merge them: v=spf1 include:spf.missioninbox.com \[your existing includes\] \~all

Still failing after 48 hours

Use a public DNS lookup tool (dig or MXToolbox) to confirm the records are publicly visible. If they appear correctly but verify still fails, contact support.

Domain verified but emails are still bouncing

Verification only confirms DNS records exist. Deliverability also depends on your domain reputation and warmup status — see the Warmup guide.

A verified domain is the prerequisite for everything else — mailboxes, warmup, and sending. Don't skip this step.

[PreviousRate Limits](https://doc.v4.missioninbox.com/sales/rate-limits.md)[NextSend Your First Email](https://doc.v4.missioninbox.com/sales/guides/send-first-email.md)
