Domains

Add a domain

Add and verify a sending domain in the dashboard or over the API, understand the verification statuses, and send from it.

You can only send from addresses on a verified domain. Adding a domain gives you DNS records to publish. Once Sooner can see them, the domain is verified and you can send from any address on it.

Add a domain in the dashboard

Open Domains and enter a domain, for example mail.yourcompany.com.
Click Add domain.
Open the domain. After a few seconds the DNS records appear, each with a copy button.
Add the records at your DNS provider. See DNS records.
Wait for the status to change to verified, or click Check DNS now.

Add a domain with the API

This needs a full_access key.

Shell

curl -X POST https://api.sooner.dev/domains \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "mail.yourcompany.com" }'

JSON

{
  "object": "domain",
  "id": "jh7b2k4d9x1m5q8r3t6v0w2y",
  "name": "mail.yourcompany.com",
  "status": "not_started",
  "region": "us-east-1",
  "created_at": "2026-11-14T10:30:00.000Z",
  "open_tracking": false,
  "click_tracking": false,
  "records": []
}

The response comes back before the records are generated, so records is empty and the status is not_started. Fetch the domain again after a few seconds to get the records:

Shell

curl https://api.sooner.dev/domains/jh7b2k4d9x1m5q8r3t6v0w2y \
  -H "Authorization: Bearer $SOONER_API_KEY"

After you publish the records, ask Sooner to check them right away:

Shell

curl -X POST https://api.sooner.dev/domains/jh7b2k4d9x1m5q8r3t6v0w2y/verify \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{ "object": "domain", "id": "jh7b2k4d9x1m5q8r3t6v0w2y" }

The region field is optional when you create a domain. Leave it out unless support has told you otherwise. See the domains API reference for all endpoints.

Naming rules

Enter a valid domain name of 3 to 253 characters, such as acme.com or mail.acme.com. It is converted to lowercase.
A domain, or any parent of it, can only be registered by one team. If another team already owns acme.com, you cannot add acme.com or mail.acme.com. Inside your own team you can add a subdomain of a domain you already registered, but the exact same name cannot be added twice.
Free plans can add up to 10 domains per team. Paid plans have no limit.
A subdomain such as mail.yourcompany.com is a good choice. It keeps your sending reputation separate from the mail you send and receive on the root domain.

Verification statuses

Status	Meaning
`not_started`	The domain was just added and its records are being generated.
`pending`	The records exist and Sooner is waiting to see them in DNS.
`verified`	The DKIM records validate. You can send from this domain.
`temporary_failure`	A temporary problem prevented the check. Sooner keeps checking.
`failed`	The records were not found in time, or they are wrong.

Sooner checks automatically, every minute for the first 10 minutes, every 5 minutes for the first 2 hours, and then every 30 minutes. If the DKIM records still do not validate after 72 hours, the status becomes failed.

Once you fix the records, click Check DNS now, or call POST /domains/{id}/verify. If DKIM now validates, the domain becomes verified.

Verification fires the domain.verified webhook event, and a failure fires domain.failed. See Event types.

Sending from a domain

A from address is accepted when its domain, or a parent of its domain, is a verified domain in the project that owns your API key. With mail.yourcompany.com verified, you can send from hello@mail.yourcompany.com and also from hello@news.mail.yourcompany.com. You cannot send from hello@yourcompany.com.

A domain belongs to one project. A key in another project cannot send from it.

Remove a domain

Delete a domain in the dashboard or with DELETE /domains/{id}. You cannot send from it afterward, and you would need to add and verify it again.