Contacts

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

List custom contact fields

GET /v1/projectId/{projectId}/contacts/fields

Parameters

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

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.

Create a custom contact field

POST /v1/projectId/{projectId}/contacts/fields

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
name	string	yes
type	string (string | number | boolean | date)	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

Response body

Field	Type	Required	Description
name	string	yes
type	string (string | number | boolean | date)	yes

Delete a custom contact field

DELETE /v1/projectId/{projectId}/contacts/fields/{name}

Parameters

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

Responses

Status	Description
200	Deleted
403	Missing or invalid API key
404	Custom contact field not found

List contacts

GET /v1/projectId/{projectId}/contacts

Accepts an API key or a whitelisted Origin header.

Parameters

Name	In	Type	Required	Description
projectId	path	string	yes	The project _id, found in the app under Project Settings.
filter	query	object		mongoose-crudl style filter object.
limit	query	integer
skip	query	integer

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.

Create a contact

POST /v1/projectId/{projectId}/contacts

Accepts an API key or a whitelisted Origin header (for client-side widget use).

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
email	string	yes
name	string
tags	array of 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
_id	string
email	string
name	string
tags	array of string
_lists	array of string		Names of subscriber lists this contact belongs to.
createdAt	string
updatedAt	string

Get a contact by email

GET /v1/projectId/{projectId}/contacts/{email}

Accepts an API key or a whitelisted Origin header.

Parameters

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

Responses

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

Response body

Field	Type	Required	Description
_id	string
email	string
name	string
tags	array of string
_lists	array of string		Names of subscriber lists this contact belongs to.
createdAt	string
updatedAt	string

Update a contact

PATCH /v1/projectId/{projectId}/contacts/{email}

Accepts an API key or a whitelisted Origin header.

Parameters

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

Request body

Field	Type	Required	Description
email	string
name	string
tags	array of 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	Contact 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
email	string
name	string
tags	array of string
_lists	array of string		Names of subscriber lists this contact belongs to.
createdAt	string
updatedAt	string

Delete a contact

DELETE /v1/projectId/{projectId}/contacts/{email}

Also removes the contact from every subscriber list. Accepts an API key or a whitelisted Origin header.

Parameters

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

Responses

Status	Description
200	Deleted
403	Missing or invalid API key
404	Contact not found

Response body

Field	Type	Required	Description
_id	string
email	string
name	string
tags	array of string
_lists	array of string		Names of subscriber lists this contact belongs to.
createdAt	string
updatedAt	string

List contacts (legacy flat URL shape)

GET /v1/contacts/{projectId}

Legacy flat URL shape, kept for backward compatibility - identical behavior to GET /v1/projectId/{projectId}/contacts above.

Parameters

Name	In	Type	Required	Description
projectId	path	string	yes	The project _id, found in the app under Project Settings.
filter	query	object		mongoose-crudl style filter object.
limit	query	integer
skip	query	integer

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.

Create a contact (legacy flat URL shape)

POST /v1/contacts/{projectId}

Legacy flat URL shape, kept for backward compatibility - identical behavior to POST /v1/projectId/{projectId}/contacts above. Accepts an API key or a whitelisted Origin header (for client-side widget use).

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
email	string	yes
name	string
tags	array of 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
_id	string
email	string
name	string
tags	array of string
_lists	array of string		Names of subscriber lists this contact belongs to.
createdAt	string
updatedAt	string

Get a contact by email (legacy flat URL shape)

GET /v1/contacts/{projectId}/{email}

Legacy flat URL shape, kept for backward compatibility - identical behavior to GET /v1/projectId/{projectId}/contacts/{email} above.

Parameters

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

Responses

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

Response body

Field	Type	Required	Description
_id	string
email	string
name	string
tags	array of string
_lists	array of string		Names of subscriber lists this contact belongs to.
createdAt	string
updatedAt	string

Update a contact (legacy flat URL shape)

PATCH /v1/contacts/{projectId}/{email}

Legacy flat URL shape, kept for backward compatibility - identical behavior to PATCH /v1/projectId/{projectId}/contacts/{email} above. Accepts an API key or a whitelisted Origin header.

Parameters

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

Request body

Field	Type	Required	Description
email	string
name	string
tags	array of 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	Contact 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
email	string
name	string
tags	array of string
_lists	array of string		Names of subscriber lists this contact belongs to.
createdAt	string
updatedAt	string

Delete a contact (legacy flat URL shape)

DELETE /v1/contacts/{projectId}/{email}

Legacy flat URL shape, kept for backward compatibility - identical behavior to DELETE /v1/projectId/{projectId}/contacts/{email} above.

Parameters

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

Responses

Status	Description
200	Deleted
403	Missing or invalid API key
404	Contact not found

Response body

Field	Type	Required	Description
_id	string
email	string
name	string
tags	array of string
_lists	array of string		Names of subscriber lists this contact belongs to.
createdAt	string
updatedAt	string

List contacts

GET /v1/projectId/{projectId}/contacts/tags

Parameters

Name	In	Type	Required	Description
projectId	path	string	yes	The project _id, found in the app under Project Settings.
limit	query	integer		Max items per page. Capped at 30.
skip	query	integer		Number of items to skip, for pagination.
sort	query	string		Field to sort by.
order	query	string
filter[<field>]	query	string		Exact-match filter on a top-level field, e.g. filter[name]=Welcome. 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.

Create a contact

POST /v1/projectId/{projectId}/contacts/tags

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
value	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
409	The resource already exists

Response body

Field	Type	Required	Description
_id	string
value	string
createdAt	string
updatedAt	string

Get a single contact

GET /v1/projectId/{projectId}/contacts/tags/{id}

Parameters

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

Responses

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

Response body

Field	Type	Required	Description
_id	string
value	string
createdAt	string
updatedAt	string

Partially update a contact

PATCH /v1/projectId/{projectId}/contacts/tags/{id}

Merges the given fields into the existing document - omitted fields are left unchanged. Nothing is required (unlike create) since every field is optional on a partial update.

Parameters

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

Request body

Field	Type	Required	Description
value	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	Contacts not found

Response body

Field	Type	Required	Description
_id	string
value	string
createdAt	string
updatedAt	string

Delete a contact

DELETE /v1/projectId/{projectId}/contacts/tags/{id}

Parameters

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

Responses

Status	Description
200	Deleted
403	Missing or invalid API key
404	Contacts not found

Response body

Field	Type	Required	Description
_id	string
value	string
createdAt	string
updatedAt	string

Resend a double opt-in verification email

POST /v1/projectId/{projectId}/subscriber-lists/{subscriberListId}/contacts/{email}/resend-verification-email

Only works while the contact is still "unverified" on the given list, and only when double opt-in is enabled (either on the list, or on the signup form they originally used).

Parameters

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

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	Contact not found

Response body

Field	Type	Required	Description
success	boolean