Domains

Full reference for the Domains resource in the bluefox.email API. See the API overview for authentication, the response envelope, and pagination.

List sending domains

GET /v1/projectId/{projectId}/domains

Not paginated - always returns every domain on the project (there are only ever a handful). Supports filter[<field>]=value exact-match filtering (e.g. filter[domain]=example.com) to look one up directly instead of scanning the full list.

Parameters

Name	In	Type	Required	Description
projectId	path	string	yes	The project _id, found in the app under Project Settings.
filter[<field>]	query	string		Exact-match filter on a top-level field, e.g. filter[domain]=example.com or filter[region]=eu-north-1. Repeatable for multiple fields.

Responses

Status	Description
200	OK
403	Missing or invalid API key

Response body

Field	Type	Required	Description
items	array
count	integer		Total matching items across all pages, not just this page.
next	string		Full URL (path + query string) of the next page, or null if this is the last page.

Add a sending domain

POST /v1/projectId/{projectId}/domains

Production-access projects only. Returns the required DNS records to add before the domain can send.

Parameters

Name	In	Type	Required	Description
projectId	path	string	yes	The project _id, found in the app under Project Settings.

Request body

Field	Type	Required	Description
domain	string	yes
region	string	yes

Responses

Status	Description
201	Created
400	Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403	Missing or invalid API key
405	The operation is blocked by a business rule (e.g. the resource is still in use)

Response body

Field	Type	Required	Description
_id	string
domain	string
region	string
tenant	object
tenant.name	string
tenant.configurationSet	string
requiredDns	object		DNS records (DKIM CNAMEs, SPF, MX, DMARC) the domain owner must add.
observed	object		Last-checked DNS verification state, per record.
observed.spf	object
observed.spf.present	boolean
observed.spf.raw	string
observed.spf.checkedAt	string
observed.dmarc	object
observed.dmarc.present	boolean
observed.dmarc.raw	string
observed.dmarc.checkedAt	string
observed.mx	object
observed.mx.present	boolean
observed.mx.raw	string
observed.mx.checkedAt	string
observed.dkim	object
observed.dkim.selectors	array of string
observed.dkim.allOk	boolean
observed.dkim.checkedAt	string
observed.allOk	boolean		True only when SPF, DMARC, MX, and DKIM are all present/verified.

Get a single domain

GET /v1/projectId/{projectId}/domains/{domainId}

Parameters

Name	In	Type	Required	Description
projectId	path	string	yes	The project _id, found in the app under Project Settings.
domainId	path	string	yes

Responses

Status	Description
200	OK
403	Missing or invalid API key
404	Domain not found

Response body

Field	Type	Required	Description
_id	string
domain	string
region	string
tenant	object
tenant.name	string
tenant.configurationSet	string
requiredDns	object		DNS records (DKIM CNAMEs, SPF, MX, DMARC) the domain owner must add.
observed	object		Last-checked DNS verification state, per record.
observed.spf	object
observed.spf.present	boolean
observed.spf.raw	string
observed.spf.checkedAt	string
observed.dmarc	object
observed.dmarc.present	boolean
observed.dmarc.raw	string
observed.dmarc.checkedAt	string
observed.mx	object
observed.mx.present	boolean
observed.mx.raw	string
observed.mx.checkedAt	string
observed.dkim	object
observed.dkim.selectors	array of string
observed.dkim.allOk	boolean
observed.dkim.checkedAt	string
observed.allOk	boolean		True only when SPF, DMARC, MX, and DKIM are all present/verified.

Remove a domain

DELETE /v1/projectId/{projectId}/domains/{domainId}

Fails while a sender identity still uses this domain/region.

Parameters

Name	In	Type	Required	Description
projectId	path	string	yes	The project _id, found in the app under Project Settings.
domainId	path	string	yes

Responses

Status	Description
200	Deleted
403	Missing or invalid API key
404	Domain not found
405	The operation is blocked by a business rule (e.g. the resource is still in use)

Response body

Field	Type	Required	Description
_id	string

Re-check DNS verification status for a domain

POST /v1/projectId/{projectId}/domains/{domainId}/check

Re-reads the DKIM/SPF/MX/DMARC DNS records for the domain. Auto-creates a default sender identity (no-reply@domain) the first time verification succeeds.

Parameters

Name	In	Type	Required	Description
projectId	path	string	yes	The project _id, found in the app under Project Settings.
domainId	path	string	yes

Responses

Status	Description
200	OK
403	Missing or invalid API key
404	Domain not found
405	The operation is blocked by a business rule (e.g. the resource is still in use)

Response body

Field	Type	Required	Description
_id	string
domain	string
region	string
tenant	object
tenant.name	string
tenant.configurationSet	string
requiredDns	object		DNS records (DKIM CNAMEs, SPF, MX, DMARC) the domain owner must add.
observed	object		Last-checked DNS verification state, per record.
observed.spf	object
observed.spf.present	boolean
observed.spf.raw	string
observed.spf.checkedAt	string
observed.dmarc	object
observed.dmarc.present	boolean
observed.dmarc.raw	string
observed.dmarc.checkedAt	string
observed.mx	object
observed.mx.present	boolean
observed.mx.raw	string
observed.mx.checkedAt	string
observed.dkim	object
observed.dkim.selectors	array of string
observed.dkim.allOk	boolean
observed.dkim.checkedAt	string
observed.allOk	boolean		True only when SPF, DMARC, MX, and DKIM are all present/verified.