Sending domains

letr.dev sends only from domains of your account that are verified. A domain is verified when its DKIM record is in DNS.

You manage domains in the dashboard or under /v1/domains. read_only and full_access keys may list and read them; only full_access may add, verify and remove them. A sending_access key gets 403 insufficient_permission, and a domain of another account answers 404 not_found. An account has at most 20 domains. The API reference lists every field.

Add a domain

Add it in the dashboard or with the API (full_access key):

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

The answer (201) lists the records to publish. letr.dev creates a new DKIM key for every domain, for at most 10 new domains an hour. A domain the account already has answers 409 domain_exists, a name that is not a domain 422 invalid_domain.

DNS records

• DKIM, required: a TXT record with your key, v=DKIM1; k=rsa; p=..., at letr._domainkey.mail.acme.dev. The value is about 750 characters. If your DNS provider allows at most 255 characters per string, enter it as several quoted strings, "v=DKIM1; k=rsa; p=abc" "def".
• DMARC, advised: a TXT record with v=DMARC1; p=none; at _dmarc.mail.acme.dev.

Bounces return to bounces.letr.dev, so your SPF record stays as it is. The DMARC record is advice: an existing record that starts with v=DMARC1 counts, and a missing one does not block sending.

Verification

A domain is pending, verified or failed. letr.dev checks a pending domain every 10 minutes, a verified one once a day at 02:20 UTC, and any domain whenever you ask (full_access):

curl -X POST https://api.letr.dev/v1/domains/$ID/verify \
  -H "Authorization: Bearer $LETR_API_KEY"

The DKIM record decides: once it matches, the domain is verified. A domain still without it 72 hours after it was added turns failed; publish the record and check again, and it turns verified. When DNS does not answer, letr.dev keeps the last status instead of guessing.

The daily check looks up the DKIM record only. When DNS answers without it at 3 checks in a row, the domain turns pending again and sends from it are refused with 422 domain_not_verified; it stays pending, not failed, and the daily check keeps checking it until the record verifies again. After the first failed check, the account owner gets a warning mail with the date and time sending stops. failedChecks and stopsSendingAt on the domain show where it stands, and the next passing check resets them. A check you ask for never counts as a failed check.

GET /v1/domains/{id} shows the domain with each record and whether it matches (ok); GET /v1/domains lists all domains of the account.

Remove a domain

DELETE /v1/domains/{id} removes a domain (full_access). Sends from it are refused afterwards with 422 domain_not_verified.