Sending domains

Why domains are verified

Mailbox providers such as Gmail and Outlook check who really sent an email. SPF, DKIM and DMARC let them confirm that email from your domain was sent with your permission. Without them, your email is often rejected or filed as spam, and anyone could send in your name.

That's why you can only send from a domain that's verified. Any address at that domain can be the sender.

Add a domain

Add the domain you want to send from. It can be your main domain, such as acme.com, or a subdomain, such as mail.acme.com. Each one counts towards your plan's sending domains (see Plans and limits).

curl -X POST https://services.my-beast.com/mail/api/email/v1/domains \
  -H "Authorization: Bearer $MYBEAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme.com"
  }'

The response is the new domain, with the DNS records to create in records.

The DNS records

Create these records at the company that runs DNS for your domain, which is often where you registered it. For acme.com they look like this:

SPF: two records on a subdomain

Every email you send carries a return address for bounce messages. Ours is on a subdomain of yours, mb-bounces.acme.com. The MX record sends bounce messages for that subdomain to us, so we can tell you about them. The TXT record is the SPF record: it says our servers may send email for that subdomain.

Because both records sit on their own subdomain, they don't change how the rest of your domain handles email. Your existing mailboxes and SPF record keep working as before.

DKIM: one record with your public key

We sign every email you send with a private key that belongs to your domain. The DKIM record, at mb1._domainkey.acme.com, publishes the matching public key. Receiving servers use it to check that the email was sent with your permission and wasn't changed on the way. The part before ._domainkey is called the selector.

DMARC: recommended

A DMARC record, at _dmarc, tells receiving servers what to do with email that claims to be from your domain but fails these checks. It isn't needed to verify your domain, but large mailbox providers expect one from domains that send a lot of email.

The suggested record uses p=none, which asks for no action and is a safe start. Once you know that all email from your domain passes, including email from other services, you can move to p=quarantine or p=reject. If you already have a DMARC record, keep it: a domain should have only one, and any valid record counts.

Verification

A domain is always in one of three states:

To check right away instead of waiting, verify the domain yourself:

curl -X POST https://services.my-beast.com/mail/api/email/v1/domains/dom_01JA2N5Q7RB3XK/verify \
  -H "Authorization: Bearer $MYBEAST_API_KEY"

A domain is verified when every required record is found with the right value. Each record in the response has its own status, verified or missing, so you can see which one needs attention.

We also check verified domains once a day. If a required record has gone, the domain becomes failed and emails from it are refused with domain_not_verified until you put the record back and verify again.

Common problems

The domain name appears twice

Many DNS providers add your domain to the end of every name you enter. If you enter mb1._domainkey.acme.com, the record ends up at mb1._domainkey.acme.com.acme.com. Enter only the part before your domain instead, such as mb1._domainkey or mb-bounces.

The DKIM value is too long

A single DNS text string can hold up to 255 characters, and DKIM keys are longer. Most providers split long values for you. If yours asks you to, split the value into several quoted strings. That's fine, as long as the parts join up to exactly the value we gave you, with nothing added.

The value has extra quotes or spaces

Copy values exactly. Some providers add quotes around text values themselves, so adding your own gives doubled quotes. Check for spaces at the start or end too.

The records aren't found yet

DNS changes can take a while to spread, depending on your provider and the records' time to live (TTL). We keep checking for 72 hours, and you can verify again whenever you like.

The domain was verified, then failed

A required record was removed or changed, often when DNS moved to another provider. Put the records back exactly as the API lists them, then verify again.

Removing a domain

Delete a domain to stop sending from it and free its place on your plan. Emails from it that are already queued are still sent, and their delivery logs are kept. Once it's deleted, you can remove its DNS records.