MailLandDocs

Add a Domain

Add and configure a sending domain in your Mail.Land workspace

Before sending email through MailLand, you need to add and verify at least one sending domain. This proves you own the domain and authorizes MailLand to send on your behalf.

Add a Domain

POST https://api.mail.land/v1/domains
Add a domain
curl -X POST https://api.mail.land/v1/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourdomain.com"
  }'

Response

Status: 201 Created

Domain response
{
  "id": "k3v9x2m8q1w7z4",
  "domain": "yourdomain.com",
  "verificationStatus": "pending",
  "spfStatus": "pending",
  "dkimStatus": "pending",
  "dmarcStatus": "pending",
  "isFullyVerified": false,
  "trackingSubdomain": "track",
  "useCustomTracking": false,
  "bounceSubdomain": "bounce",
  "useCustomBounce": true,
  "inboundEnabled": false,
  "inboundSubdomain": null,
  "mxVerified": false,
  "healthStatus": "unknown",
  "createdAt": "2026-02-17T10:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z"
}
FieldTypeDescription
idstringDomain public ID
domainstringThe domain name
verificationStatusenumpending, verified, or failed
spfStatus / dkimStatus / dmarcStatusenumpending, valid, or invalid per record
isFullyVerifiedbooleanOwnership verified AND SPF, DKIM and DMARC all valid, required to send
trackingSubdomain / bounceSubdomainstringSubdomains used for tracking/bounce, whether or not the custom domain is enabled
useCustomTracking / useCustomBouncebooleanWhether the custom tracking/bounce domain is turned on
inboundEnabledbooleanWhether inbound email receiving is on for this domain
inboundSubdomainstring | nullSubdomain for the inbound MX record; null means the domain root
mxVerifiedbooleanWhether the inbound MX record is verified
healthStatusenumunknown, healthy, warning, or critical
createdAtdatetimeWhen the domain was added

There is no verification token: adding a domain creates the record and generates its DKIM key automatically (no token step).

After adding a domain, you need to configure DNS records and verify ownership before you can send email. See DNS Setup for the required records.

Setup Flow

Add the domain

Call POST /v1/domains with your domain name. MailLand creates the domain record and generates its DKIM key.

Get DNS instructions

Call GET /v1/domains/{id}/dns-instructions to retrieve the exact DNS records you need to create. See DNS Setup.

Configure DNS records

Add the SPF, DKIM and DMARC records (plus the optional bounce/tracking CNAMEs if enabled) to your DNS provider.

Verify the domain

Call POST /v1/domains/{id}/verify to trigger verification. MailLand checks all DNS records and updates the domain status. See Verification.

List Domains

GET https://api.mail.land/v1/domains
List domains
curl https://api.mail.land/v1/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
List response
{
  "items": [
    {
      "id": "k3v9x2m8q1w7z4",
      "domain": "yourdomain.com",
      "verificationStatus": "verified",
      "spfStatus": "valid",
      "dkimStatus": "valid",
      "dmarcStatus": "valid",
      "isFullyVerified": true,
      "trackingSubdomain": "track",
      "useCustomTracking": false,
      "bounceSubdomain": "bounce",
      "useCustomBounce": false,
      "inboundEnabled": false,
      "inboundSubdomain": null,
      "mxVerified": false,
      "healthStatus": "healthy",
      "createdAt": "2026-02-17T10:00:00Z",
      "updatedAt": "2026-02-17T10:15:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Get a Domain

GET https://api.mail.land/v1/domains/{id}

Returns the full domain details including verification status and all subdomains.

Get a domain
curl https://api.mail.land/v1/domains/k3v9x2m8q1w7z4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Update Domain Settings

Customize tracking and bounce subdomains, and toggle inbound. Other settings fields: useCustomTracking, useCustomBounce, inboundEnabled, inboundSubdomain. These labels only take effect once the corresponding custom flag is on and the record is verified. Turning useCustomBounce on clears the bounce record's verification, so you must verify its CNAME again:

PATCH https://api.mail.land/v1/domains/{id}/settings
Update domain settings
curl -X PATCH https://api.mail.land/v1/domains/k3v9x2m8q1w7z4/settings \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "trackingSubdomain": "links",
    "bounceSubdomain": "returns"
  }'

Changing subdomains requires updating your DNS records and re-verifying the domain.

Delete a Domain

DELETE https://api.mail.land/v1/domains/{id}

Returns 204 No Content on success. Deleting a domain:

  • Revokes all DKIM keys associated with the domain
  • Stops all email sending from this domain
  • Removes tracking and bounce routing
Delete a domain
curl -X DELETE https://api.mail.land/v1/domains/k3v9x2m8q1w7z4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Deletion is permanent. Any API credentials scoped to this domain will no longer be able to send email. Active campaigns or automations using this domain will fail.

Error Responses

StatusCodeDescription
400VALIDATION_FAILEDInvalid domain name format
400INVALID_REQUESTDomain already added (to this workspace or another)
404DOMAIN_NOT_FOUNDDomain ID does not exist
403PLAN_LIMIT_REACHEDMaximum domains for your plan reached
400DOMAIN_SUBDOMAIN_EMPTYPATCH settings: a subdomain field was sent empty
400DOMAIN_SUBDOMAIN_CONFLICTPATCH settings: the requested subdomain is already used by another record on this domain

MailLand limits the number of sending domains by plan, and the limit differs per plan (some plans are unlimited). Once you reach it, adding a domain returns 403 PLAN_LIMIT_REACHED. See your current plan under Billing.

Next Steps

On this page

Add a DomainResponseSetup FlowAdd the domainGet DNS instructionsConfigure DNS recordsVerify the domainList DomainsGet a DomainUpdate Domain SettingsDelete a DomainError ResponsesNext Steps