Sending Domains

Every email you send must originate from a verified sending domain. PostMTA validates SPF, DKIM, and DMARC records to establish sender authenticity and protect deliverability.

Overview

A sending domain is the domain portion of the MAIL FROM address (also called the envelope sender or return path). PostMTA requires all sending domains to pass three DNS verification checks before they can be used for production delivery.

• SPF — authorizes PostMTA's mail servers to send on your behalf.
• DKIM — cryptographically signs message headers so they cannot be tampered with.
• DMARC — ties SPF and DKIM together with a policy for handling failures.

Adding a Domain

Domains can be added through the dashboard or via the REST API. After addition, you are given the exact DNS records to publish.

REST API

curl -X POST https://api.postmta.com/v1/domains \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mail.example.com",
    "default": true
  }'

Response:

{
  "id": "dom_01HX5K9P7N3M4Q6R8T2V4W6Y0",
  "domain": "mail.example.com",
  "status": "pending_verification",
  "SPF_pass": false,
  "DKIM_pass": false,
  "DMARC_pass": false,
  "dkim_selector": "pmx1",
  "default": true,
  "created_at": "2026-07-18T12:00:00Z"
}

Dashboard

Navigate to /app/domains and click Add Domain. Enter your subdomain (e.g., mail or marketing). PostMTA will display the three DNS records you must add.

SPF Record Setup

SPF (Sender Policy Framework) is a TXT record published on the sending domain that lists which mail servers are authorized to send email for that domain.

Record format

Create a TXT record on mail.example.com:

Type:  TXT
Host:   mail.example.com
Value:  "v=spf1 include:_spf.postmta.com ~all"

What the record means

• v=spf1 — declares this as an SPF record (version 1).
• include:_spf.postmta.com — authorizes all PostMTA outbound servers.
• ~all — soft fail: emails from unlisted servers are marked as suspicious but not rejected by receivers. Use -all (hard fail) only after you are confident the record is correct.

Multiple authorized senders

If you send from multiple providers, include each one:

"v=spf1 include:_spf.postmta.com include:_spf.google.com include:_spf.mailsender.com ~all"

DKIM Record Setup

DKIM (DomainKeys Identified Mail) adds a cryptographic signature to every outgoing message. PostMTA generates a unique DKIM key pair for each domain and provides you with the public key as a DNS record.

Record format

Create a CNAME record pointing to PostMTA's DKIM selector:

Type:  CNAME
Host:   pmx1._domainkey.mail.example.com
Value:  pmx1._domainkey.postmta.com

pmx1 is the DKIM selector assigned to your domain (shown in the dashboard and API response as dkim_selector). Do not change the selector value — it must match what PostMTA uses when signing your messages.

Verification

After adding the CNAME, verify DKIM status via API:

curl https://api.postmta.com/v1/domains/dom_01HX5K9P7N3M4Q6R8T2V4W6Y0 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

When DKIM_pass becomes true, the DKIM signature is valid.

DMARC Record Setup

DMARC (Domain-based Message Authentication, Reporting & Conformance) ties SPF and DKIM together with a policy telling receiving servers what to do when authentication fails.

Record format

Create a TXT record on _dmarc.mail.example.com:

Type:  TXT
Host:   _dmarc.mail.example.com
Value:  "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@example.com; ruf=mailto:dmarc-forensics@example.com"

Policy values

Aggregate and forensic reports

• rua — aggregate reports sent daily listing pass/fail counts per receiving domain.
• ruf — forensic reports sent immediately for each authentication failure.

Verified From in Production

PostMTA enforces PMH-SEC-026: the MAIL FROM domain must be a verified sending domain in your workspace. This means:

• You cannot use a domain you do not own or control.
• All three verification records (SPF, DKIM, DMARC) must pass.
• The From header domain should match or be a subdomain of the verified domain.

If a message is submitted with a MAIL FROM from an unverified domain, the SMTP session is rejected with:

550 5.7.1 Unverified sender domain. Please add and verify this domain in your PostMTA dashboard.

Subdomain Delegation

For multi-brand or multi-product sending, use a parent domain for DNS management and delegate subdomains to individual product teams without re-verifying the parent domain for each subdomain.

Pattern

Register mail.example.com as the parent verified domain. Each product team uses a subdomain such as alerts.mail.example.com ormarketing.mail.example.com. Only the parent domain needs the three DNS records; subdomains inherit the authentication.

# Parent domain (verified once):
mail.example.com   TXT   "v=spf1 include:_spf.postmta.com ~all"
pmx1._domainkey.mail.example.com  CNAME  pmx1._domainkey.postmta.com
_dmarc.mail.example.com  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com"

# Product subdomain (inherits parent authentication — no additional DNS needed):
alerts.mail.example.com
marketing.mail.example.com

Rules

• Subdomains must be exactly one level deep under the verified parent (no deeper nesting).
• Each subdomain intended for sending should be added as its own sending domain in PostMTA for tracking purposes.
• DKIM signing uses the parent's selector; no per-subdomain DKIM records are required.

Domain Verification Troubleshooting

Next Steps

• SMTP Authentication — connect with AUTH PLAIN and OAuth 2.0
• Sending Email — send via REST or SMTP relay
• Custom Headers — add List-Unsubscribe, X-Priority, and other headers
• Webhooks — receive delivery events for your verified domains