Subscriptions

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

List subscribers of a list

GET /v1/subscriber-lists/{id}

Legacy flat URL shape. Auth: API key (Authorization: Bearer) matching the list's project, OR an admin/account-owner JWT.
Unlike GET /v1/projectId/{projectId}/contacts (where custom field values are flat top-level keys), here they are
returned nested under a "customFields" object, e.g. { "email": "x@y.com", "customFields": { "plan": "pro" } }.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The subscriber list _id.

Responses

Status	Description
200	OK
403	Missing or invalid API key

Response body

Field	Type	Required	Description
items	array of object
items[].email	string
items[].status	string (unverified | active | unsubscribed | paused)
items[].customFields	object		Custom contact field values, keyed by field name.
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.

Subscribe a contact to a list

POST /v1/subscriber-lists/{id}

Legacy flat URL shape. Creates the contact if it doesn't exist yet. Triggers double opt-in if enabled on the list. Auth: API key, or a whitelisted Origin (in which case a CAPTCHA is required unless the list disables it).

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The subscriber list _id.

Request body

Field	Type	Required	Description
email	string	yes
name	string
status	string (unverified | active)
captchaText	string
captchaProbe	string

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
status	string
email	string

Get a subscriber by email

GET /v1/subscriber-lists/{id}/{email}

Legacy flat URL shape. Accepts an API key or a whitelisted Origin header.
Unlike GET /v1/projectId/{projectId}/contacts/{email} (where custom field values are flat top-level keys), here they
are returned nested under a "customFields" object, e.g. { "email": "x@y.com", "customFields": { "plan": "pro" } }.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The subscriber list _id.
email	path	string	yes

Responses

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

Response body

Field	Type	Required	Description
email	string
status	string (unverified | active | unsubscribed | paused)
customFields	object		Custom contact field values, keyed by field name.

Update a subscriber (status, contact fields, pause/resubscribe)

PATCH /v1/subscriber-lists/{id}/{email}

Legacy flat URL shape. Setting status to "paused" requires pausedUntil (a future date). Accepts an API key or a whitelisted Origin header.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The subscriber list _id.
email	path	string	yes

Request body

Field	Type	Required	Description
email	string
status	string (active | paused | unsubscribed)
pausedUntil	string

Responses

Status	Description
200	OK
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
404	Subscriber not found
405	The operation is blocked by a business rule (e.g. the resource is still in use)

One-click unsubscribe

POST /v1/subscriber-lists/{id}/{email}/unsubscribe

Legacy flat URL shape. Not API-key authenticated - requires a signed one-click-unsubscribe token (the ?token= query param from a dispatched email's List-Unsubscribe link).

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The subscriber list _id.
email	path	string	yes
token	query	string	yes

Responses

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

Submit a hosted/embedded signup form

POST /v1/signup-forms/{id}

Legacy flat URL shape. Not API-key authenticated - requires a whitelisted Origin header, and (depending on the form config) a CAPTCHA. Subscribes the contact to every list configured on the form.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The signup form _id.

Request body

Field	Type	Required	Description
email	string	yes
name	string
captchaText	string
captchaProbe	string
turnstileToken	string
termsAccepted	boolean

Responses

Status	Description
201	OK
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
success	boolean
redirectTo	string