Appearance
Sender Identities
Full reference for the Sender Identities resource in the bluefox.email API. See the API overview for authentication, the response envelope, and pagination.
List sender identities
GET /v1/projectId/{projectId}/sender-identities
There is no separate "default" flag - the first item in the returned list is the default sender identity (used when an email doesn't specify one). Use POST .../set-default to change which one is first. Not paginated - always returns every identity on the project. Supports filter[<field>]=value exact-match filtering (e.g. filter[email]=support@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[email]=support@example.com. 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 sender identity
POST /v1/projectId/{projectId}/sender-identities
The email's domain must be a verified domain on this project, in the given region.
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 | The domain part must match a verified domain on this project in the given region. |
name | string | ||
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 |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
email | string | ||
name | string | ||
region | string |
Set a sender identity as the default
POST /v1/projectId/{projectId}/sender-identities/{identityId}/set-default
Moves this identity to the front of the sender identities list - the position that determines which one is used by default.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
identityId | path | string | yes |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 403 | Missing or invalid API key |
| 404 | Sender identity not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
email | string | ||
name | string | ||
region | string |
Delete a sender identity
DELETE /v1/projectId/{projectId}/sender-identities/{identityId}
Fails while a campaign, transactional email, triggered email, or automation email still uses it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
identityId | path | string | yes |
Responses
| Status | Description |
|---|---|
| 200 | Deleted |
| 403 | Missing or invalid API key |
| 404 | Sender identity 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 |