Sign in to fill these examples with your own keys. Sign in Start free trial

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.

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

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, select Download BIND file and import it at your DNS host. If your DNS is on Cloudflare and the default DKIM CNAME is in use, Add records in Cloudflare may appear. 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?.

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.

domain.json
1{ 2 "sending_domain": { 3 "name": "mail.example.com", 4 "tenant_id": "WbLcFd" 5 } 6}

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.

If Spamhaus lists your domain

We check every sending domain against the Spamhaus Domain Block List each hour. 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. 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.

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.

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