Domains
Add sending domains, publish DKIM, SPF and DMARC records and verify them.
Add a domain
/api/v1/domainsRequires domains:writeRegisters a domain in your workspace and generates a 2048-bit RSA DKIM key pair for it. The response contains the DNS records you need to publish.
curl -X POST https://mail.example.com/api/v1/domains \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domain": "acme.com"
}'domainstringrequired- The domain you send from, for example acme.com or mail.acme.com.
selectorstring- DKIM selector, 2 to 16 lowercase letters or digits. Defaults to
mf1.
Response
{
"data": {
"id": "0a4d9a52-0a8e-4f4e-b4f7-6f4f6a2f9a11",
"domain": "acme.com",
"dkim_selector": "mf1",
"dkim_public_key": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...",
"spf_verified": false,
"dkim_verified": false,
"dmarc_verified": false,
"inbound_mx_verified": false,
"status": "pending",
"created_at": "2026-11-20T18:01:44.120Z",
"dnsRecords": [
{
"type": "TXT",
"purpose": "DKIM",
"host": "mf1._domainkey.acme.com",
"value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."
},
{
"type": "TXT",
"purpose": "SPF",
"host": "acme.com",
"value": "v=spf1 include:mta1.example.com ~all"
},
{
"type": "TXT",
"purpose": "DMARC",
"host": "_dmarc.acme.com",
"value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@acme.com"
},
{
"type": "MX",
"purpose": "INBOUND_MX",
"host": "inbound.acme.com",
"value": "inbound.example.com",
"priority": 10
}
]
}
}Adding a domain that already exists in the workspace returns 409.
DNS records
| Purpose | Type | Host | Why |
|---|---|---|---|
| DKIM | TXT | mf1._domainkey.acme.com | Lets receivers check that mail was signed with your key. |
| SPF | TXT | acme.com | Authorises your mail server to send for the domain. |
| DMARC | TXT | _dmarc.acme.com | Tells receivers what to do with mail that fails DKIM and SPF. |
| Inbound MX | MX | inbound.acme.com | Only needed if you want to receive mail. |
The SPF include host and the inbound MX host come from the server settings MAILFORGE_SPF_HOST and MAILFORGE_INBOUND_MX_HOST.
Verify a domain
/api/v1/domains/{id}/verifyRequires domains:writeLooks up the live DNS records and stores the result on the domain. Call it again after you change DNS. Propagation can take from a few minutes to a few hours.
curl -X POST https://mail.example.com/api/v1/domains/0a4d9a52-0a8e-4f4e-b4f7-6f4f6a2f9a11/verify \
-H "Authorization: Bearer $MAILFORGE_API_KEY"{
"data": {
"id": "0a4d9a52-0a8e-4f4e-b4f7-6f4f6a2f9a11",
"domain": "acme.com",
"spf_verified": true,
"dkim_verified": true,
"dmarc_verified": true,
"inbound_mx_verified": false,
"status": "verified"
},
"verification": {
"dkimVerified": true,
"spfVerified": true,
"dmarcVerified": true,
"inboundMxVerified": false,
"status": "verified"
}
}| Status | Meaning |
|---|---|
verified | DKIM and SPF records were found. |
partial | At least one record was found, but DKIM or SPF is still missing. |
pending | No record was found yet. |
List domains
/api/v1/domainsRequires domains:readReturns every domain of the workspace with its verification state and DNS records.
curl https://mail.example.com/api/v1/domains \
-H "Authorization: Bearer $MAILFORGE_API_KEY"Get or delete a domain
/api/v1/domains/{id}Requires domains:readReturns one domain with its verification state and, in dnsRecords, the records to publish.
/api/v1/domains/{id}Requires domains:writeRemoves the domain and its DKIM key. In production, mail from this domain is refused afterwards.
curl -X DELETE https://mail.example.com/api/v1/domains/eab2654c-08bc-4191-9ddd-a876cf2efe8d \
-H "Authorization: Bearer $MAILFORGE_API_KEY"{
"ok": true,
"id": "eab2654c-08bc-4191-9ddd-a876cf2efe8d"
}