# Managing domains

> Add a sending domain, work through DNS verification, re-verify, and delete domains.

A **domain** is the identity you send from. MailBlastr creates a sending identity for it (DKIM signing plus a custom MAIL FROM subdomain), then gives you the SPF, DKIM, and DMARC DNS records to publish. Once those records are confirmed, the domain is **verified** and you can send from any address on it.

A verified domain also covers its **subdomains** — a domain identity for `example.com` signs and authorizes mail from `news.example.com`, so you do not need to add each subdomain separately.

## Add a domain

Add a domain in the dashboard under **Domains**, or via the API with [`POST /domains`](https://www.mailblastr.com/docs/api/domains-create). MailBlastr provisions the sending identity and returns the domain object with the DNS records to publish.

> **Note:** You add the bare domain (e.g. `yourdomain.com`). Publish the returned records at your DNS provider — see [DNS records](https://www.mailblastr.com/docs/domains/dns).

## Verification lifecycle

A domain moves through a small set of statuses. A freshly added domain starts at `not_started`; once you trigger verification it moves to `pending` while it waits for DNS to propagate and DKIM to be confirmed.

| Status | Meaning |
| --- | --- |
| `not_started` | The status right after creation, before any verification has run. Per-record statuses also start here. |
| `pending` | Verification has been triggered and MailBlastr is waiting to confirm the published DNS records. |
| `verified` | The identity and DKIM signing were confirmed. The domain (and its subdomains) can send email. |
| `failed` | DKIM verification failed — the records were not found within the verification window (MailBlastr checks for up to **72 hours**) or are incorrect. Fix the DNS and re-verify. |
| `temporary_failure` | A previously `verified` domain whose DNS records can no longer be detected. MailBlastr rechecks for 72 hours: if the records reappear it returns to `verified`; if not it becomes `failed`. Re-publish the missing records and re-verify. |
| `revoked` | A different account verified this domain (or a parent/subdomain of it) by publishing its DNS records, so this account’s verification was withdrawn. Sending from it is blocked. Re-verify to take it back if you still control the DNS. |

> **Warning:** You can only send from a **verified** domain (or a subdomain of one). Sending from an unverified domain returns a `validation_error`.

> **Note:** For deliverability we recommend sending from a **subdomain** (e.g. `updates.yourdomain.com` or `news.yourdomain.com`) rather than your root domain. This isolates your sending reputation and signals intent to recipients. A verified domain identity already covers its subdomains, so a single `yourdomain.com` identity authorizes `updates.yourdomain.com` without adding it separately.

## One verified owner per domain

A domain — together with its parents and subdomains — can be verified by **at most one account** at a time. Adding a domain that overlaps a domain another account has already verified returns a `validation_error`; if you own the domain, prove it with the [domain claim flow](https://www.mailblastr.com/docs/domains/claim) instead.

Because verification requires publishing DNS records, whoever completes verification provably controls the DNS — so when a domain is verified, any overlapping domain verified under a **different** account moves to `revoked` and can no longer send. The revoked account is notified by email and, if subscribed, receives a `domain.updated` webhook with the new status.

## Re-verify

DNS changes can take time to propagate, so a domain may sit at `pending` for a while after you publish the records. Trigger a fresh check with [`POST /domains/:id/verify`](https://www.mailblastr.com/docs/api/domains-verify) (or the **Verify** button in the dashboard). MailBlastr re-checks your DNS and updates the domain and per-record status — `verified`, `failed`, or still `pending`.

## Custom return path

The **return path** (the `MAIL FROM` / bounce address) defaults to the `send.yourdomain.com` subdomain — this is the subdomain that carries the SPF MX and TXT records. You can choose a different label by passing the optional `custom_return_path` field when creating the domain; the SPF records are then published on that subdomain (e.g. `outbound.yourdomain.com`) instead of `send.`.

- Must be **63 characters or less**.
- Must start with a letter, end with a letter or number, and contain only letters, numbers, and hyphens.

> **Warning:** Avoid values that could undermine credibility (e.g. `testing`) — the return-path subdomain is exposed to recipients in some mail clients.

## Enforced TLS

Each domain carries a `tls` preference that records how you want mail from it encrypted in transit. **Opportunistic** (the default) encrypts the connection to the receiving server when that server supports TLS, and otherwise sends unencrypted. **Enforced** records a preference that delivery should require TLS — use it when confidentiality matters more than guaranteed delivery. Set it with [`PATCH /domains/:id`](https://www.mailblastr.com/docs/api/domains-update) (`tls`).

## Delete a domain

Delete a domain in the dashboard or with [`DELETE /domains/:id`](https://www.mailblastr.com/docs/api/domains-delete). This removes the sending identity and the stored records.

> **Warning:** Deletion is **blocked while a scheduled email still depends on the domain** — you get a `validation_error` asking you to cancel that email first. This prevents a scheduled send from firing against a domain MailBlastr no longer has an identity for.