Domains

Add sending domains, publish DKIM, SPF and DMARC records and verify them.

Add a domain

POST/api/v1/domainsRequires domains:write

Registers 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"
  }'
Body parameters
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

201 Created
{
  "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

PurposeTypeHostWhy
DKIMTXTmf1._domainkey.acme.comLets receivers check that mail was signed with your key.
SPFTXTacme.comAuthorises your mail server to send for the domain.
DMARCTXT_dmarc.acme.comTells receivers what to do with mail that fails DKIM and SPF.
Inbound MXMXinbound.acme.comOnly 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

POST/api/v1/domains/{id}/verifyRequires domains:write

Looks 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"
Response
{
  "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"
  }
}
StatusMeaning
verifiedDKIM and SPF records were found.
partialAt least one record was found, but DKIM or SPF is still missing.
pendingNo record was found yet.

List domains

GET/api/v1/domainsRequires domains:read

Returns 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

GET/api/v1/domains/{id}Requires domains:read

Returns one domain with its verification state and, in dnsRecords, the records to publish.

DELETE/api/v1/domains/{id}Requires domains:write

Removes 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"
Response
{
  "ok": true,
  "id": "eab2654c-08bc-4191-9ddd-a876cf2efe8d"
}