Domains and DNS

Add, publish, verify

POST /domains with a name. GET /domains/{id} returns the records to publish. POST /domains/{id}/verify re-checks them. Verification is a DNS read, so it is only as fast as your registrar's propagation — minutes usually, longer if your TTLs are long.

Region

region is optional and defaults to us (Oregon). Pass eu for Helsinki. The stored value is on every domain response. It is a data-residency and egress choice; it cannot be changed later. For this release the names us-east-1, sa-east-1 and ap-northeast-1 still map to us, and eu-west-1 maps to eu.

The records

For notify.example.com, GET /domains/{id} returns:

• DKIM signs each message with a key only we hold, so receivers can prove the message was not altered and did come from you. Publish the whole value on one line; a key truncated at 255 bytes by a DNS editor is the commonest reason DKIM never resolves. Required.
• SPF names the hosts allowed to send for the domain. It goes on the domain root, which is where receivers check it while the envelope sender is still your From address. Required.
• DMARC tells receivers what to do when the other two fail, and asks them to report. Start at p=none with a reporting address, read the reports for a week, then move to quarantine. Recommended, not required — a domain verifies and sends without it, and the record shows as recommended rather than failing.
• Return path is a subdomain of *your* domain (send. by default). The MX lets bounces come back to us; the TXT keeps SPF aligned with your domain. Optional — sending works without it. Until both records resolve, the envelope sender stays your From address. After they resolve, it becomes a signed address on send.notify.example.com.
• Tracking is a host on *your* domain that opens and clicks are counted on (default links.notify.example.com). Optional; it never blocks verification, and both tracking switches stay off until you turn them on. The CNAME appears on GET /domains/{id} when tracking is available. Until then, and until the CNAME resolves, links go out as you wrote them. Tracking never uses a shared AgentiSend hostname.
• Tracking CAA is a CAA record on that same host. Shown only if this domain already limits which authorities may issue certificates and that set does not already allow ours. Without a restriction, any authority can issue and this record is omitted. Verification checks it when it is published; it never blocks sending.

GET /domains list items omit the DNS records (use GET /domains/{id} for the sheet). The tracking subdomain can be changed with PATCH /domains/{id} (tracking_subdomain); it cannot be removed. Changing it regenerates the tracking records as pending and stops rewriting links until you verify again. Signed click URLs on the previous host keep redirecting for 30 days.

Name, region, and return-path cannot change on an existing domain — add a new domain instead.

Open tracking on a transactional send (receipts, resets, alerts) returns a warning explaining that inbox providers can mistake that mail for marketing. Broadcasts do not warn. The send is never blocked.

If you already have an SPF record

A name may carry exactly one SPF record; two invalidate both. So merge ours into the record that is already there rather than adding a second one. Either form verifies:

v=spf1 ip4:5.78.29.80 ip4:5.78.29.195 ip4:5.78.28.193 ip4:5.78.24.66 ip4:65.109.252.126 ip4:116.202.178.98 include:_spf.mailprovider.example -all
v=spf1 include:_spf.agentisend-dns.com include:_spf.mailprovider.example -all

_spf.agentisend-dns.com holds the same six addresses, so the include form stays correct if we add an IP. include:_spf.agentisend.com still authorises us. Verification accepts either: all six ip4: mechanisms present, or either include — and the include only when that name currently publishes every sending IP. An include that does not resolve does not authorise us.

The return-path MX we show is feedback.agentisend-dns.com. mta1.agentisend.com still verifies if that is what is already published.

The same merge rule applies on send. if that name already has an SPF record.

Use a subdomain for application mail

Send from mail.yourdomain.com or notifications.yourdomain.com rather than the apex. The reputation of your receipts and your password resets then cannot be damaged by anything else the company sends, and the reverse is also true.

What verification checks

POST /domains/{id}/verify reads DNS and rolls the answers up. A domain is verified when DKIM and SPF both resolve. It is partially verified — and can still send — when those two resolve and only the return-path records do not. Tracking, Tracking CAA, and DMARC never move the domain's status in either direction. A wrong tracking CNAME is marked failed on that row, and sending still works. Return-path is used only after both of its records resolve. The detail and the verify response list which tracking records are missing and what each does.

Click tracking and open tracking default to off. Open tracking is a one-pixel image: Apple Mail Privacy Protection loads it whether or not anyone read the message, and most other clients block it. Treat the number as a trend, never as a count. Leave it off for receipts and alerts.

Verification can be lost

A required record that is edited away later moves the domain out of verified and fires domain.failed. Sends from it are refused with domain_not_verified, whose fix names POST /domains/{id}/verify. Subscribe to the domain.* events so this reaches you before a customer does.