Skip to content
MiniMailer
Docs
Toggle sidebar
Quick links
Documentation
Knowledge Base
API Reference
Changelog
No results found

Domains

Sending domain management operations.

POST /domains

Create a sending domain

Registers a new sending domain and returns it in the pending state. MiniMailer generates the DKIM, SPF, and MAIL FROM (MX) records you must publish in DNS before it will send from the domain.

Verification flow

  1. Fetch the generated records from GET /domains/{domain}/records.
  2. Publish them at your DNS provider.
  3. MiniMailer polls DNS and advances the domain pending → verifying → active. It lands on failed if the records do not resolve within the verification window.

A domain must be active before any transactional or campaign email can be sent from it. Domain names are unique per account. Requires the domains:write scope.

Request body

application/vnd.api+json — CreateDomainRequestDocument

Attribute
Type
Description
name required string Fully qualified domain name.
purpose required string
region string
mail_from_prefix string
tls_policy string
POST /domains 
curl -X POST https://api.minimailer.app/domains \
  -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"domains","attributes":{"name":"...","purpose":"...","region":"...","mail_from_prefix":"...","tls_policy":"..."}}}'

Responses

Status
Description
201 Sending domain created. DomainDocument
401 Authentication is required. ErrorDocument
403 The authenticated token does not have permission to perform this action. ErrorDocument
415 The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset). ErrorDocument
422 The request document failed validation. ValidationErrorDocument
409 The request conflicts with the endpoint or current state: the document's resource type does not match the endpoint, its id does not match the resource being updated, or an idempotency key was reused with a different payload. (Creating with a client-generated id and updating relationships on an endpoint that does not support them return 403 instead.) ErrorDocument
406 The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains. ErrorDocument
429 The caller exceeded the API rate limit. ErrorDocument
GET /domains

List sending domains

Returns the authenticated user's sending domains, newest first. Supports the JSON:API filter, sort, include, and sparse fields query parameters. Requires the domains:read scope.

Parameters

Name
In
Description
filter query Exact-match filters, e.g. filter[status]=delivered. Only the fields this endpoint allow-lists are accepted; an unsupported filter returns 400.
sort query Comma-separated sort fields; prefix a field with - for descending, e.g. sort=-created_at,name. Defaults to newest-first. Only allow-listed fields are accepted; an unsupported sort returns 400.
include query Comma-separated related resources to embed in the response included member (JSON:API compound documents). Example: include=records,webhooks. Nested paths use dot notation, max depth 2. Relationships not declared by the resource, or over-deep paths, return 400.
fields query Per-type sparse fieldsets. Example: fields[domains]=name,status restricts the returned attributes for that type. The type must be present in the document and each field must be a known attribute, otherwise 400 is returned.
page query Cursor-based pagination, e.g. page[cursor]=eyJpZCI6...&page[size]=50. The cursor is an opaque token issued by the API — take it from the response's links.next / links.prev URLs or meta.next_cursor / meta.prev_cursor; never construct one. size defaults to 25 and is silently capped at 100 (out-of-range or non-numeric values fall back to the default). An invalid or expired cursor falls back to the first page; a cursor replayed with a different sort than it was issued under returns 400; unknown page members such as page[number] return 400. Follow links.next until it is null (or meta.has_more is false) to traverse a collection; links.first restarts traversal. Link URLs carry these parameters URL-encoded (page%5Bcursor%5D=...).
GET /domains 
curl -X GET https://api.minimailer.app/domains \
  -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Responses

Status
Description
400 The include or fields query parameter is not supported (unknown relationship, over-deep include, or unknown sparse-fieldset type or field). ErrorDocument
200 Sending domains retrieved. DomainCollectionDocument
401 Authentication is required. ErrorDocument
403 The authenticated token does not have permission to perform this action. ErrorDocument
406 The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains. ErrorDocument
429 The caller exceeded the API rate limit. ErrorDocument
GET /domains/{domain}

Show a sending domain

Returns a single sending domain owned by the authenticated user, including its current verification status (pending, verifying, active, suspended, or failed). Requires the domains:read scope.

Parameters

Name
In
Description
include query Comma-separated related resources to embed in the response included member (JSON:API compound documents). Example: include=records,webhooks. Nested paths use dot notation, max depth 2. Relationships not declared by the resource, or over-deep paths, return 400.
fields query Per-type sparse fieldsets. Example: fields[domains]=name,status restricts the returned attributes for that type. The type must be present in the document and each field must be a known attribute, otherwise 400 is returned.
domain required path The domain identifier.
GET /domains/{domain} 
curl -X GET https://api.minimailer.app/domains/{domain} \
  -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Responses

Status
Description
400 The include or fields query parameter is not supported (unknown relationship, over-deep include, or unknown sparse-fieldset type or field). ErrorDocument
200 Sending domain retrieved. DomainDocument
401 Authentication is required. ErrorDocument
403 The authenticated token does not have permission to perform this action. ErrorDocument
404 The requested resource could not be found. ErrorDocument
406 The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains. ErrorDocument
429 The caller exceeded the API rate limit. ErrorDocument
PATCH /domains/{domain}

Update a sending domain

Updates the mutable settings of a sending domain owned by the authenticated user. Four operations are supported, individually or together:

  • TLS policy — set Require or Optional transport encryption.
  • MAIL FROM prefix — changing it re-issues the MX/SPF records and reverts an active domain to verifying until the new records resolve.
  • DKIM key rotation — set rotate_dkim_key; a new selector is generated and the domain returns to verifying until its record is published.
  • Open/click tracking — toggle tracking and choose the redirect mode. branded (per-customer redirect domain) requires a Growth plan or above, otherwise 422.

The domain name itself is immutable. Requires the domains:write scope.

Parameters

Name
In
Description
domain required path The domain identifier.

Request body

application/vnd.api+json — UpdateDomainRequestDocument

Attribute
Type
Description
tls_policy string
mail_from_prefix string
rotate_dkim_key boolean
open_tracking_enabled boolean
click_tracking_enabled boolean
tracking_redirect_mode string
PATCH /domains/{domain} 
curl -X PATCH https://api.minimailer.app/domains/{domain} \
  -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"domains","attributes":{"tls_policy":"...","mail_from_prefix":"...","rotate_dkim_key":true,"open_tracking_enabled":true,"click_tracking_enabled":true,"tracking_redirect_mode":"..."}}}'

Responses

Status
Description
200 Sending domain updated. DomainDocument
401 Authentication is required. ErrorDocument
403 The authenticated token does not have permission to perform this action. ErrorDocument
404 The requested resource could not be found. ErrorDocument
415 The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset). ErrorDocument
422 The request document failed validation. ValidationErrorDocument
409 The request conflicts with the endpoint or current state: the document's resource type does not match the endpoint, its id does not match the resource being updated, or an idempotency key was reused with a different payload. (Creating with a client-generated id and updating relationships on an endpoint that does not support them return 403 instead.) ErrorDocument
406 The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains. ErrorDocument
429 The caller exceeded the API rate limit. ErrorDocument
DELETE /domains/{domain}

Delete a sending domain

Removes a sending domain owned by the authenticated user and tears down its sending configuration. The DKIM secret is retained for a 7-day recovery window before permanent deletion.

The domain row is soft-deleted so existing sends, campaigns, and suppressions keep their reference for audit and GDPR retention; their statistics remain queryable. Sending from the domain stops immediately. If the teardown fails the domain is left suspended and the request returns 502. Requires the domains:write scope.

Parameters

Name
In
Description
domain required path The domain identifier.
DELETE /domains/{domain} 
curl -X DELETE https://api.minimailer.app/domains/{domain} \
  -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Responses

Status
Description
204 Sending domain deleted.
401 Authentication is required. ErrorDocument
403 The authenticated token does not have permission to perform this action. ErrorDocument
404 The requested resource could not be found. ErrorDocument
406 The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains. ErrorDocument
429 The caller exceeded the API rate limit. ErrorDocument
GET /domains/{domain}/records

List domain DNS records

Returns the DNS records (DKIM, SPF, MAIL FROM MX, and DMARC where applicable) that must be published at your DNS provider to verify and use a sending domain. Each record carries its record_type, name, value, ttl, and a verified flag so you can track which entries MiniMailer has already confirmed.

Poll this endpoint after publishing records to watch verification progress. Requires the domains:read scope.

Parameters

Name
In
Description
filter query Exact-match filters, e.g. filter[status]=delivered. Only the fields this endpoint allow-lists are accepted; an unsupported filter returns 400.
sort query Comma-separated sort fields; prefix a field with - for descending, e.g. sort=-created_at,name. Defaults to newest-first. Only allow-listed fields are accepted; an unsupported sort returns 400.
include query Comma-separated related resources to embed in the response included member (JSON:API compound documents). Example: include=records,webhooks. Nested paths use dot notation, max depth 2. Relationships not declared by the resource, or over-deep paths, return 400.
fields query Per-type sparse fieldsets. Example: fields[domains]=name,status restricts the returned attributes for that type. The type must be present in the document and each field must be a known attribute, otherwise 400 is returned.
page query Cursor-based pagination, e.g. page[cursor]=eyJpZCI6...&page[size]=50. The cursor is an opaque token issued by the API — take it from the response's links.next / links.prev URLs or meta.next_cursor / meta.prev_cursor; never construct one. size defaults to 25 and is silently capped at 100 (out-of-range or non-numeric values fall back to the default). An invalid or expired cursor falls back to the first page; a cursor replayed with a different sort than it was issued under returns 400; unknown page members such as page[number] return 400. Follow links.next until it is null (or meta.has_more is false) to traverse a collection; links.first restarts traversal. Link URLs carry these parameters URL-encoded (page%5Bcursor%5D=...).
domain required path The domain identifier.
GET /domains/{domain}/records 
curl -X GET https://api.minimailer.app/domains/{domain}/records \
  -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Responses

Status
Description
400 The include or fields query parameter is not supported (unknown relationship, over-deep include, or unknown sparse-fieldset type or field). ErrorDocument
200 Domain DNS records retrieved. RecordCollectionDocument
401 Authentication is required. ErrorDocument
403 The authenticated token does not have permission to perform this action. ErrorDocument
404 The requested resource could not be found. ErrorDocument
406 The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains. ErrorDocument
429 The caller exceeded the API rate limit. ErrorDocument