Domains and DNS setup

Add a sending domain to Scribase Mail and publish the DKIM, SPF (return-path), DMARC and optional MX records. What each record does, how verification works, and how to fix failed records.

Mail from your domain is trusted when the receiving server can check three things: the message is signed by your domain (DKIM), the server that sent it is allowed to (SPF, checked on the return-path), and you have said what to do when those fail (DMARC). Adding a domain gives you the exact records; publishing them takes a few minutes at your DNS provider.

Add the domain

curl -X POST https://mail-api.scribase.com/domains \
  -H "Authorization: Bearer $SCRIBASE_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme.com", "return_path": "send", "open_tracking": false, "click_tracking": false }'

{
  "object": "domain",
  "id": "79e60a61-36e4-45bb-a88b-4633220a96d9",
  "name": "acme.com",
  "status": "not_started",
  "created_at": "2026-11-12 21:15:12.548+00:00",
  "region": "eu-frankfurt-1",
  "return_path": "send",
  "open_tracking": false,
  "click_tracking": false,
  "dkim_selector": "scribase",
  "capabilities": { "sending": "enabled", "receiving": "disabled" },
  "records": [
    { "record": "DKIM",  "name": "scribase._domainkey", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..." },
    { "record": "SPF",   "name": "send", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "v=spf1 include:rp.oracleemaildelivery.com ~all" },
    { "record": "DMARC", "name": "_dmarc", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "v=DMARC1; p=none;" }
  ]
}

name is the domain your from addresses use (hello@acme.com). A sub-domain such as mail.acme.com keeps your main domain's reputation separate; many teams use one for transactional and another for marketing. return_path is the label of the bounce sub-domain (default send); change it if that name is taken.

Fields: name (required), region (default eu-frankfurt-1), return_path (one DNS label), open_tracking, click_tracking (booleans, default off).

The records

Record name values are relative to your domain: scribase._domainkey means scribase._domainkey.acme.com. Some DNS providers want the full name, some only the relative part; the UI usually says. Copy value exactly.

Record	Host	Type	What it does
DKIM	`scribase._domainkey.acme.com`	TXT	Publishes the public half of the RSA-2048 key we sign your messages with. Receivers see `dkim=pass` with `d=acme.com`, which is what Gmail and Outlook require from every sender. Generated per domain; you never see the private key. Required for `verified`.
SPF	`send.acme.com`	TXT	Lists the servers allowed to send with `send.acme.com` as the bounce (return-path) address. The return-path is on a sub-domain so your main domain's own SPF record stays untouched, and so SPF and DKIM both align with `acme.com` for DMARC. Required for `verified`.
MX (when shown)	`send.acme.com`	MX, priority 10	Points bounce traffic for the return-path at our inbound server so hard bounces reach your suppression list. Appears when our inbound MX is configured for your region. Reported, not required.
DMARC	`_dmarc.acme.com`	TXT	Tells receivers what to do when SPF and DKIM both fail. `p=none` is the safe starting point; it only asks for reports. Move to `p=quarantine` once your own mail is all signed. If you already have a DMARC record, keep yours. Reported, not required for `verified`; required to send on the Free plan.

Our SPF value includes our current sending network (rp.oracleemaildelivery.com). When we move to our own IPs the include target stays the same, so you do not have to touch DNS again.

Verify

curl -X POST https://mail-api.scribase.com/domains/$DOMAIN_ID/verify \
  -H "Authorization: Bearer $SCRIBASE_MAIL_API_KEY"
# { "object": "domain", "id": "79e60a61-..." }

curl https://mail-api.scribase.com/domains/$DOMAIN_ID \
  -H "Authorization: Bearer $SCRIBASE_MAIL_API_KEY"

Verification does real DNS lookups right then and stores the result on each record (verified or failed). The domain's status becomes:

verified when DKIM TXT and SPF TXT both match;
pending when one of them matches;
failed when neither does yet;
not_started before the first check.

DNS changes can take from a minute to a few hours to propagate. Run verify again; nothing is cached on our side. DKIM is matched on the p= key only, so providers that split a long TXT into quoted chunks are fine. SPF is matched ignoring whitespace and case.

Sending from a domain that is not verified returns 403 validation_error: The acme.com domain is not verified. Please, add and verify your domain.

Typical fixes

Symptom	Cause	Fix
DKIM `failed`, record looks right	Provider added the domain twice: `scribase._domainkey.acme.com.acme.com`	Enter only `scribase._domainkey` as the host, or the full name without a trailing duplicate
DKIM `failed`, value truncated	Provider limits a TXT string to 255 characters	Most providers split it automatically; otherwise paste it as two quoted strings in one record
SPF `failed`	You pasted the SPF value on `acme.com` instead of `send.acme.com`	SPF belongs on the return-path sub-domain
Mail lands in spam with `dmarc=fail`	A different DMARC record on `_dmarc.acme.com` with strict alignment, or no DMARC at all	Keep one DMARC record; `p=none; adkim=r; aspf=r` is compatible
Verified, but Gmail shows "via"	Open tracking changed links and `From` domain differs from DKIM `d=`	Send from an address on the verified domain itself

Tracking

Open and click tracking are off by default and set per domain (PATCH /domains/{id} with open_tracking / click_tracking). When on, we append a 1x1 pixel served from /track/open/... and rewrite http(s) links in the HTML through /track/click/..., both signed so they cannot be forged. Opens and clicks surface as email.opened / email.clicked webhooks. Many privacy-conscious products leave both off for transactional mail.

Unsubscribe headers

Every message carries List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058) pointing at a hosted /unsubscribe/{token} endpoint. A one-click unsubscribe from Gmail or Yahoo adds the recipient to your suppression list within a second, which is what their 2024 bulk-sender rules require. You do not need to add anything.

Delete

curl -X DELETE https://mail-api.scribase.com/domains/$DOMAIN_ID \
  -H "Authorization: Bearer $SCRIBASE_MAIL_API_KEY"
# { "object": "domain", "id": "...", "deleted": true }

Remove the DNS records afterwards; a stale DKIM public key is harmless but tidy DNS is easier to debug.