Domains

To send from your own address, add its domain, publish the DNS records you get back, and wait for verification. Until then you can send from your sandbox domain, sandbox.avelto.dev, to your own account email and to the simulator addresses.

Add a domain

Use a subdomain such as mail.acme.com rather than the root domain. It keeps your website's DNS untouched and keeps sending reputation separate.

curl -X POST https://api.avelto.dev/v1/domains \  -H "Authorization: Bearer av_live_..." \  -H "Content-Type: application/json" \  -d '{    "name": "mail.acme.com"  }'

{  "id": "1d3f2b7e-0d4a-4e5b-8d0c-6a7e9f1b2c3d",  "name": "mail.acme.com",  "region": "eu-north-1",  "status": "pending",  "ownership_verified": false,  "dns_records": [    {      "type": "TXT",      "name": "_avelto.mail.acme.com",      "value": "avelto-verification=3f9c1a7e5b2d4c8e9a0b6d1f2e3c4a5b",      "purpose": "ownership"    },    {      "type": "TXT",      "name": "mail.acme.com",      "value": "v=spf1 include:spf.avelto.dev ~all",      "purpose": "spf"    },    {      "type": "TXT",      "name": "_dmarc.mail.acme.com",      "value": "v=DMARC1; p=none;",      "purpose": "dmarc"    }  ],  "health": "unknown",  "health_changed_at": null,  "dns_checks": null,  "dns_checked_at": null,  "created_at": "2026-09-17T10:00:00.000Z"}

The domain starts as pending, with ownership_verified: false.

Some names cannot be added, and return 409:

• conflict: the name is already added, on your account or on another one.
• domain_unavailable: the name is part of a domain on another account (a subdomain or a parent of it), is one of ours, or is already set up elsewhere. If it is yours, contact support.

You can add subdomains of a domain that is already on your own account.

Publish the records

Verification takes two steps, so that only someone who controls the domain's DNS can send from it.

1. Prove the domain is yours. The response lists one ownership record, with a value unique to this domain:

Publish it at your DNS provider. Until we find it, nothing is set up for sending, and a domain whose ownership record is not found within 7 days of being added is removed (you can add it again).

2. Publish the DKIM records. Once the ownership record is found, ownership_verified becomes true and dns_records lists the remaining records. The ownership record drops out of the list, and you can remove it from your DNS.

The SPF and DMARC records are listed from the start, so you can publish them alongside the ownership record.

Verification itself checks the three DKIM CNAMEs, so a domain can verify and send before SPF is in place. SPF is still required: until the record carries our include, the dashboard counts it as missing and the domain shows action needed once verified. DMARC is recommended.

If you already publish an SPF record, for example for the mailboxes on your domain, add include:spf.avelto.dev to it instead of replacing it or creating a second one. A name can only have one SPF record, and replacing yours would make the mail you already send fail its checks. So v=spf1 include:mx.example.net ~all becomes v=spf1 include:spf.avelto.dev include:mx.example.net ~all. That one include covers our sending infrastructure, and it stays valid if the infrastructure behind it changes.

Check verification

You do not have to poll. Once you have published the records, we keep checking a pending domain in the background, for the ownership record first and then for DKIM: every five minutes for the first hour after you add it, then hourly until it is three days old. When it verifies, the account owner gets an email and a notification in the dashboard, and the domain is ready to send from. The dashboard shows the DKIM records as soon as the ownership record is found.

If you would rather know straight away, GET /v1/domains/:id also re-checks verification on every call while the domain is pending and updates ownership_verified, dns_records and status. status becomes verified once the CNAMEs resolve, or failed if verification is abandoned, the name is verified on another account, or it turns out to be set up elsewhere (contact support if it is yours). After three days the background checks stop and the domain stays pending; fix the records, then call it again (or press Check now in the dashboard). A domain whose ownership record was never found is removed at seven days.

curl https://api.avelto.dev/v1/domains/1d3f2b7e-0d4a-4e5b-8d0c-6a7e9f1b2c3d \  -H "Authorization: Bearer av_live_..."

DNS changes usually propagate in minutes, sometimes up to a few hours depending on your provider's TTLs.

Send

Once the domain is verified, any from address on it works: hello@mail.acme.com, Acme <billing@mail.acme.com>, and so on. Sending from an unverified or unknown domain returns 403 domain_not_verified. The check is made again when the email goes out, so a scheduled email from a domain you have since removed fails with email.failed instead of sending.

Remove a domain

curl -X DELETE https://api.avelto.dev/v1/domains/1d3f2b7e-0d4a-4e5b-8d0c-6a7e9f1b2c3d \  -H "Authorization: Bearer av_live_..."

Returns 204. Emails already sent from it keep their records; scheduled emails from it fail when their time comes.

Domain health

Verification is a moment; staying verified is not. A DNS provider migration, an expired zone edit or a tidy-up of "unused" records can quietly undo any of this months later, and the first sign is usually mail landing in spam.

So we keep looking. Every night we re-resolve each verified domain's DKIM, SPF and DMARC records and compare them with what we expect. The domains page in your dashboard shows each record's state side by side: what we expect, what actually resolved, and whether that is a match, a mismatch or nothing at all.

If a DKIM or SPF record stops matching, the domain is marked action needed: the domain's row in your dashboard shows that pill and the DNS health table, an entry goes into your audit log, and we email you if you have domain health alerts switched on. A missing DMARC record never triggers this on its own, because running without one is a choice rather than a fault.

You can re-check a domain yourself from the dashboard at any time. That button is limited to once a minute per domain so an impatient refresh cannot hammer your DNS provider.

Limits

• Free includes one domain; Pro and above have no limit. Adding a domain past the limit returns 403 plan_limit.
• New accounts can add up to 5 domains in their first 7 days.
• A domain whose ownership record is not found within 7 days of being added is removed.

See Plans and limits for what each plan includes.