Domains and DNS

When you add a domain, Letterpier creates its records: a unique ownership token and a new 2048-bit DKIM key among them. Five are needed to send: ownership, DKIM, SPF, return path and DMARC. The sixth, MX, is only needed if the domain also receives mail. Publish them at your DNS provider, exactly as shown in the dashboard. Any TTL works.

• Ownership proves the domain is yours. A domain belongs to one project, across all of Letterpier.
• DKIM signs every message. The private key never leaves Letterpier and its mail server.
• SPF and the return path let receiving servers check where the mail came from, and send bounces back to Letterpier.
• MX routes mail for the domain to Letterpier. Publish it only if you turn receiving on; see Receiving is optional.
• DMARC tells receiving servers what to do with mail that fails those checks.

A new domain sends only. Turn on catch-all receiving when you add the domain, or later on the domain’s page in the dashboard, and turn it off the same way. While it is on, the MX record is required and mail to any address on the domain arrives in its project. While it is off, no mail for the domain reaches the project, and the domain needs no MX record.

The MX record never holds up sending. capabilities.receiving in the domain’s response is disabled while receiving is off, pending until the domain is verified and MX matches, and enabled after that; receiving_enabled shows the setting itself. Through the API, pass receiving: true when you create the domain. The SDK’s domains.create doesn’t send that field, so use a plain HTTP request:

POST /domains HTTP/1.1Host: app.letterpier.comAuthorization: Bearer lp_live_…Content-Type: application/json{ "name": "notify.yourproduct.example", "receiving": true }

To change the setting later, use the switch on the domain’s page. The dashboard sends PATCH /api/control/projects/:projectId/domains/:id with { "receiving": true } or false and gets the updated domain back. That control API takes a signed-in dashboard session, not an API key; the Resend-compatible API has no update route for domains yet.

How receiving works

While records are missing, the domain’s page in the dashboard checks them every 30 seconds on its own. To check straight away, select Check now or call mail.domains.verify(id). Letterpier looks up all the records at once. When the five sending records match, the domain is verified and sending is turned on. If receiving is on, it starts as soon as MX matches too.

Per project, you can add up to 5 domains per minute and run up to 10 verifications per minute.

// Full-access key. Creates a sending-only domain.const { data: domain } = await mail.domains.create({  name: 'notify.yourproduct.example',});domain?.records; // MX is required only with receiving onawait mail.domains.verify(domain!.id); // Checks the records nowconst { data: checked } = await mail.domains.get(domain!.id);checked?.status; // 'verified' once the sending records match

You don’t have to verify again by hand. While a new domain waits for its records, Letterpier’s worker checks it about every 2 minutes for its first 7 days, so it verifies soon after your DNS changes appear. Every other domain is re-checked once its last check is 6 hours old, so a healthy domain stays inside the 24-hour window on its own. If a sending record stops matching, the domain shows Needs attention (or Waiting for DNS when the record is gone), and sending and receiving on it pause until you fix the record and a check finds it again. If only MX stops matching, sending carries on and receiving shows as pending.

A name can have only one SPF record. If yours already has one, for another provider, don’t add a second: add Letterpier’s include to the existing one, before its all term.

v=spf1 include:_spf.otherprovider.example include:spf.letterpier.com -all

• Letterpier accepts the record when it has exactly one SPF policy with include:spf.letterpier.com before the all term, and doesn’t allow everyone (+all, or a bare all).
• SPF allows at most 10 DNS lookups per check. Letterpier’s include uses one; count the others before you add it.

If the domain has no DMARC policy, publish v=DMARC1; p=none;: it asks receiving servers to report without changing delivery. Once every service that sends as your domain passes SPF or DKIM, raise it to p=quarantine or p=reject.

If a policy already exists, keep it. Letterpier accepts any single DMARC record with p=none, p=quarantine or p=reject. For a subdomain without its own record, it accepts the policy of the registered domain above it.

Reverse DNS belongs to the sending IP address, not to your domain. Letterpier’s IP has one PTR record for mail.letterpier.com, with a matching forward record, and every project’s domains share it. There is nothing to publish per domain.

A subdomain such as notify.yourproduct.example is often the better choice: its SPF record stays apart from the main domain’s, and if you turn receiving on, its MX record doesn’t touch mail for the main domain. Add it to Letterpier as its own domain: the sender address of a live message must use a verified domain exactly, so hello@notify.yourproduct.example needs notify.yourproduct.example itself to be verified.

Each record shows its status after every check, with a short detail from the API.

The domain’s own status sums them up: