# Managing domains

> How to create, verify, import, suspend, flush, and delete a sending domain.

Add a sending domain, publish its DNS records, and keep it healthy from the dashboard. Every action here also has an API route on [Sending domains](/docs/api-reference/domains).

## Before you start

- You need the Team Administrator role to add or change a domain.
- Use a domain you control, such as `example.com`. A single word such as `mta` is rejected. See [Subdomain or root domain?](/docs/knowledge-base/is-it-better-to-send-emails-from-a-subdomain).

## Add a domain

1. In the sidebar, open **Sending** → **Domains & Tenants**, then select **Add domain**.
2. Enter the **Domain**, such as `example.com`.
3. If your team has extra tenants, choose the **Tenant**. Only SMTP users on that tenant can send as the domain.
4. Most domains need nothing else. Open **Advanced** only to change the **DKIM selector** from `ps1`, or to check **Use my own DKIM key** and paste an existing key into **DKIM private key**.
5. Select **Add domain**.

## Publish and verify DNS

The domain page lists each record under **DNS records**, with its name, type, value, and status.

1. Publish the DKIM record and the `rp` return-path CNAME at your DNS host. The DMARC record is optional.
2. Select **Check DNS**. PostShiba also re-checks on its own for a few minutes after you add the domain.
3. Send once **Check DNS** reports `Domain verified.` With your own TXT, `You can send.` also means the domain is ready.

To publish faster, import the BIND file at your DNS host. When we recognize the host, the button names it, for example **Add records in Cloudflare**, and shows that host's import steps. Mail CNAMEs on Cloudflare must stay DNS-only.

If a check fails, the page says which record is wrong and where it was found. See [What if my domain is not verifying?](/docs/knowledge-base/what-if-my-domain-is-not-verifying).

## Create a domain with the API

POST this body to `/api/v1/teams/:obfuscated_team_id/sending_domains`. `tenant_id` is optional and defaults to the default tenant.

```json domain.json
{
  "sending_domain": {
    "name": "mail.example.com",
    "tenant_id": "WbLcFd"
  }
}
```

The response carries `dkim_status`, `return_path_status`, and `sending_allowed`. Default DKIM can send when both statuses are `verified`. With your own TXT, `dkim_status` `verified` is enough.

## Change or refresh DKIM

- **Edit DKIM** changes the selector, switches to your own TXT, or imports a private key.
- **Refresh keys** issues a new keypair and sets `dkim_status` back to `pending`.

Both break authentication and sending until you publish the new DKIM record and it verifies.

## Suspend or resume a domain

Select **Suspend** to pause sending from that domain. Select **Resume** to turn it back on. DNS records stay in place either way.

While a domain is paused, REST sends return `403` `domain_suspended`, and SMTP and HTTP inject return `550` `domain_suspended`.

If **Resume** says the domain is still on the Spamhaus Domain Block List, clear that listing first, then resume. The API route is `POST /api/v1/sending_domains/:sending_domain_id/resume`. See [Errors](/docs/api-reference/errors).

## If Spamhaus lists your domain

We check a domain against the Spamhaus Domain Block List as soon as you add it, every hour while it sends or for its first week, and every day after that. When a domain is listed, we pause sending from it and email your Team Administrators. The domain shows **Blocklisted**, and its page explains the listing. Your other domains keep sending.

To start sending again:

1. Look up the domain at [check.spamhaus.org](https://check.spamhaus.org/). If the parent domain is listed, such as `example.com` for `mail.example.com`, that listing blocks the subdomain too.
2. Fix what caused the listing. The usual causes are mail to bought or scraped lists, a signup form that bots fill in with other people's addresses, and links to a site that is itself listed.
3. Request removal on the Spamhaus lookup page.
4. Once Spamhaus removes the listing, open the domain and select **Resume sending**. We check the listing again first. If the domain is still listed, it stays paused and the page says so.

## If we pause a domain for unknown recipients

Each hour we look at the last 3 hours of mail from every domain that sent at least 3,000 messages in that time. If 10% or more of those messages bounced because the address does not exist, we pause sending from the domain and email your Team Administrators. A rate that high usually means a bought, scraped, or old list, and mailbox providers block senders who keep mailing one. The domain page shows how many messages went to unknown addresses. Your other domains keep sending.

To start sending again:

1. Find the list or signup form behind these sends. If the domain belongs to one of your customers, ask them where the addresses came from.
2. Remove the addresses that bounced. Confirm new signups before you mail them.
3. Open the domain and select **Resume sending**. Only mail sent after you resume counts toward the next check. If unknown recipients stay at 10% or more, we pause the domain again.

With the API, `GET /api/v1/sending_domains/:id` returns `suspended_reason: unknown_recipients` while the domain is paused this way, and `POST /api/v1/sending_domains/:id/resume` turns it back on.

## Sender addresses we refuse

We refuse mail whose sender names a brand that phishing often impersonates, such as `coinbase`, `paypal`, or `microsoft`. We check the address (its local part and domain) and the display name people see in their inbox, so `PayPal <hello@example.com>` is refused too. We check common lookalikes, such as `paypa1`, `c0inbase`, and `Pay Pal`. The check runs on SMTP, HTTP inject, and the send API. Over SMTP, the message is refused with `550 5.7.1` and the matched word. The send API returns `403` with `error: sender_blocked`. Only that message is refused. The domain and your account keep sending.

If you send legitimate mail for one of these brands, open a support ticket.

## Flush a queue

The domain page shows how many messages are **queued** (waiting to send). **Flush queue**, in the page's **More** menu, drops every queued message for that domain. Mail you send from it in the next 5 minutes is dropped too. This cannot be undone.

Dropped mail bounces with the reason `flushed by sender`. Recipients are not added to the suppression list.

The API route is `POST /api/v1/sending_domains/:id/flush_queue`.

## Make a domain primary

The first domain you add is the account primary. Outbound mail from other domains is also DKIM-signed with it. **Make primary** appears on any other verified domain that is not suspended. Select it to move the second signature.

To sign each message only with its own domain, open **Domains & Tenants**, select **DKIM signing**, and clear **Also sign with the primary domain**. With the API, `PATCH /api/v1/teams/:team_id/dkim_signing` with `sign_with_primary_domain: false`. See [DKIM signing](/docs/api-reference/dkim-signing).

## Remove a domain

Select **Remove**, then confirm. PostShiba blocks removal while a live inbox uses the domain. Disable those inboxes first. Disabled inboxes are detached when the domain goes.

## Next steps

- [Verified domains](/docs/dashboard/domains/introduction)
- [Return-path](/docs/dashboard/domains/custom-return-path)
- [Add and verify a domain](/docs/add-a-domain)
- [Sending domains API](/docs/api-reference/domains)