Braze Email Lists & Addresses API
Users email subscription status can be updated and retrieved via Braze using a RESTful API. You can use the API to set up bi-directional sync between Braze and other email systems or your own database.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/braze-email-lists-addresses-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Braze Email Lists & Addresses API
description: The Braze and Radar integration allows you to access sophisticated location-based campaign triggers and user profile enrichment with rich, first-party location data.
version: 1.0.0
servers:
- url: https://rest.iad-01.braze.com
description: REST endpoint for instance US-01
- url: https://rest.iad-01.braze.com
description: REST endpoint for instance US-01
- url: https://rest.iad-02.braze.com
description: REST endpoint for instance US-02
- url: https://rest.iad-03.braze.com
description: REST endpoint for instance US-03
- url: https://rest.iad-04.braze.com
description: REST endpoint for instance US-04
- url: https://rest.iad-05.braze.com
description: REST endpoint for instance US-05
- url: https://rest.iad-06.braze.com
description: REST endpoint for instance US-06
- url: https://rest.iad-08.braze.com
description: REST endpoint for instance US-08
- url: https://rest.fra-01.braze.eu
description: REST endpoint for instance EU-01
- url: https://rest.fra-02.braze.eu
description: REST endpoint for instance EU-02
security:
- BearerAuth: []
tags:
- name: Email Lists & Addresses
description: Users email subscription status can be updated and retrieved via Braze using a RESTful API. You can use the API to set up bi-directional sync between Braze and other email systems or your own database.
paths:
/email/hard_bounces:
get:
tags:
- Email Lists & Addresses
summary: Query Hard Bounced Emails
description: '> Use this endpoint to pull a list of email addresses that have hard bounced your email messages within a certain time frame.
To use this endpoint, youll need to generate an API key with the `email.hard_bounces` permission.
**Note:** You must provide an `end_date`, as well as either an `email` or a `start_date`. If you provide all three, `start_date`, `end_date`, and an `email`, we prioritize the emails given and disregard the date range.
If your date range has more than `limit` number of hard bounces, you will need to make multiple API calls, each time increasing the `offset` until a call returns either fewer than `limit` or zero results.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
## Example request
```
curl --location --request GET ''https://rest.iad-01.braze.com/email/hard_bounces?start_date=2019-01-01&end_date=2019-02-01&limit=100&offset=1&email=example@braze.com'' \
--header ''Authorization: Bearer YOUR-API-KEY-HERE''
```
## Response
Entries are listed in descending order.
``` json
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
"emails": [
{
"email": "example1@braze.com",
"hard_bounced_at": "2016-08-25 15:24:32 +0000"
},
{
"email": "example2@braze.com",
"hard_bounced_at": "2016-08-24 17:41:58 +0000"
},
{
"email": "example3@braze.com",
"hard_bounced_at": "2016-08-24 12:01:13 +0000"
}
],
"message": "success"
}
```'
parameters:
- name: Authorization
in: header
schema:
type: string
example: Bearer {{api_key}}
- name: start_date
in: query
schema:
type: string
description: "(Optional*) String in YYYY-MM-DD format \n\nStart date of the range to retrieve hard bounces, must be earlier than `end_date`. This is treated as midnight in UTC time by the API.\n\n*You must provide either an `email` or a `start_date`, and an `end_date`.\n"
example: '2019-01-01'
- name: end_date
in: query
schema:
type: string
description: '(Optional*) String in YYYY-MM-DD format
String in YYYY-MM-DD format. End date of the range to retrieve hard bounces. This is treated as midnight in UTC time by the API.
*You must provide either an `email` or a `start_date`, and an `end_date`.'
example: '2019-02-01'
- name: limit
in: query
schema:
type: integer
description: '(Optional) Integer
Optional field to limit the number of results returned. Defaults to 100, maximum is 500.'
example: 100
- name: offset
in: query
schema:
type: integer
description: '(Optional) Integer
Optional beginning point in the list to retrieve from.'
example: 1
- name: email
in: query
schema:
type: string
description: '(Optional*) String
If provided, we will return whether or not the user has hard bounced.
*You must provide either an `email` or a `start_date`, and an `end_date`.'
example: example@braze.com
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
operationId: getEmailHardBounces
x-operation-id-source: derived
/email/unsubscribes:
get:
tags:
- Email Lists & Addresses
summary: Query List of Unsubscribed Email Addresses
description: '> Use this endpoint to return emails that have unsubscribed during the time period from `start_date` to `end_date`.
You can use this endpoint to set up a bi-directional sync between Braze and other email systems or your own database.
To use this endpoint, youll need to generate an API key with the `email.unsubscribe` permission.
**Note:** You must provide an `end_date`, as well as either an `email` or a `start_date`.
If your date range has more than `limit` number of unsubscribes, you will need to make multiple API calls, each time increasing the `offset` until a call returns either fewer than `limit` or zero results.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
## Example request
```
curl --location --request GET ''https://rest.iad-01.braze.com/email/unsubscribes?start_date=2020-01-01&end_date=2020-02-01&limit=1&offset=1&sort_direction=desc&email=example@braze.com'' \
--header ''Authorization: Bearer YOUR-API-KEY-HERE''
```
## Response
Entries are listed in descending order.
``` json
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
"emails": [
{
"email": "example1@braze.com",
"unsubscribed_at": "2016-08-25 15:24:32 +0000"
},
{
"email": "example2@braze.com",
"unsubscribed_at": "2016-08-24 17:41:58 +0000"
},
{
"email": "example3@braze.com",
"unsubscribed_at": "2016-08-24 12:01:13 +0000"
}
],
"message": "success"
}
```'
parameters:
- name: Authorization
in: header
schema:
type: string
example: Bearer {{api_key}}
- name: start_date
in: query
schema:
type: string
description: '(Optional*) String in YYYY-MM-DD format
Start date of the range to retrieve unsubscribes, must be earlier than end_date. This is treated as midnight in UTC time by the API.'
example: '2020-01-01'
- name: end_date
in: query
schema:
type: string
description: '(Optional*) String in YYYY-MM-DD format
End date of the range to retrieve unsubscribes. This is treated as midnight in UTC time by the API.'
example: '2020-02-01'
- name: limit
in: query
schema:
type: integer
description: '(Optional) Integer
Optional field to limit the number of results returned. Limit must be greater than 1. Defaults to 100, maximum is 500.'
example: 1
- name: offset
in: query
schema:
type: integer
description: "(Optional) Integer \n\nOptional beginning point in the list to retrieve from."
example: 1
- name: sort_direction
in: query
schema:
type: string
description: '(Optional) String
Pass in the value `asc` to sort unsubscribes from oldest to newest. Pass in `desc` to sort from newest to oldest. If sort_direction is not included, the default order is newest to oldest.'
example: desc
- name: email
in: query
schema:
type: string
description: '(Optional*) String
If provided, we will return whether or not the user has unsubscribed.'
example: example@braze.com
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
operationId: getEmailUnsubscribes
x-operation-id-source: derived
/email/status:
post:
tags:
- Email Lists & Addresses
summary: Change Email Subscription Status
description: '> Use this endpoint to set the email subscription state for your users. Users can be `opted_in`, `unsubscribed`, or `subscribed` (not specifically opted in or out).
You can set the email subscription state for an email address that is not yet associated with any of your users within Braze. When that email address is subsequently associated with a user, the email subscription state that you uploaded will be automatically set.
To use this endpoint, youll need to generate an API key with the `email.status` permission.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
## Request parameters
| Parameter | Required | Data Type | Description |
| --- | --- | --- | --- |
| `email` | Required | String or array | String email address to modify, or an array of up to 50 email addresses to modify. |
| `subscription_state` | Required | String | Either subscribed, unsubscribed, or opted_in. |'
requestBody:
content:
application/json:
schema:
type: object
example:
email: example@braze.com
subscription_state: subscribed
properties:
email:
type: string
format: email
subscription_state:
type: string
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: Authorization
in: header
schema:
type: string
example: Bearer {{api_key}}
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
'201':
description: Successful response
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
operationId: postEmailStatus
x-operation-id-source: derived
/email/bounce/remove:
post:
tags:
- Email Lists & Addresses
summary: Remove Hard Bounced Emails
description: '> Use this endpoint to remove email addresses from your Braze bounce list.
We will also remove them from the bounce list maintained by your email provider.
To use this endpoint, youll need to generate an API key with the `email.bounce.remove` permission.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
## Request parameters
| Parameter | Required | Data Type | Description |
| --- | --- | --- | --- |
| `email` | Required | String or array | String email address to modify, or an array of up to 50 email addresses to modify. |'
requestBody:
content:
application/json:
schema:
type: object
example:
email: example@braze.com
properties:
email:
type: string
format: email
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: Authorization
in: header
schema:
type: string
example: Bearer {{api_key}}
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
'201':
description: Successful response
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
operationId: postEmailBounceRemove
x-operation-id-source: derived
/email/spam/remove:
post:
tags:
- Email Lists & Addresses
summary: Remove Email Addresses from Spam List
description: '> Use this endpoint to remove email addresses from your Braze spam list.
We will also remove them from the spam list maintained by your email provider.
To use this endpoint, youll need to generate an API key with the `email.spam.remove` permission.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
## Request parameters
| Parameter | Required | Data Type | Description |
| --- | --- | --- | --- |
| `email` | Required | String or array | String email address to modify, or an array of up to 50 email addresses to modify. |'
requestBody:
content:
application/json:
schema:
type: object
example:
email: example@braze.com
properties:
email:
type: string
format: email
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: Authorization
in: header
schema:
type: string
example: Bearer {{api_key}}
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
'201':
description: Successful response
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
operationId: postEmailSpamRemove
x-operation-id-source: derived
/email/blocklist:
post:
tags:
- Email Lists & Addresses
summary: Blocklist Email Addresses
description: '> Use this endpoint to unsubscribe a user from email and mark them as hard bounced.
To use this endpoint, youll need to generate an API key with the `email.blacklist` permission.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
## Request parameters
| Parameter | Required | Data Type | Description |
| --- | --- | --- | --- |
| `email` | Required | String or array | String email address to blacklist, or an array of up to 50 email addresses to blocklist. |'
requestBody:
content:
application/json:
schema:
type: object
example:
email:
- blocklist_email1
- blocklist_email2
properties:
email:
type: array
items:
type: string
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: Authorization
in: header
schema:
type: string
example: Bearer {{api_key}}
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
'201':
description: Successful response
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
operationId: postEmailBlocklist
x-operation-id-source: derived
/email/blacklist:
post:
tags:
- Email Lists & Addresses
summary: Blacklist Email Addresses
description: '> Use this endpoint to unsubscribe a user from email and mark them as hard bounced.
To use this endpoint, youll need to generate an API key with the `email.blacklist` permission.
## Rate limit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
## Request parameters
| Parameter | Required | Data Type | Description |
| --- | --- | --- | --- |
| `email` | Required | String or array | String email address to blacklist, or an array of up to 50 email addresses to blocklist. |'
requestBody:
content:
application/json:
schema:
type: object
example:
email:
- blacklist_email1
- blacklist_email2
properties:
email:
type: array
items:
type: string
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: Authorization
in: header
schema:
type: string
example: Bearer {{api_key}}
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
'201':
description: Successful response
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
operationId: postEmailBlacklist
x-operation-id-source: derived
components:
responses:
Unauthorized:
description: 401 Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: 400 Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: 404 Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: 403 Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalServerError:
description: 500 Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: 429 Rate Limited
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
message:
type: string
errors:
type: array
items:
type: string
securitySchemes:
BearerAuth:
type: http
scheme: bearer