openapi: 3.0.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. When Radar geofence or trip tracking events are generated, custom events and user attributes are sent to Braze in real-time. These events and attributes can then be used to trigger location-based campaigns, power last-mile pickup and delivery operations, monitor fleet and shipping logistics, or build user segments based on location patterns. '
  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. \n  \n\nTo use this endpoint, youll need to generate an API key with the `email.hard_bounces` permission.\n\n**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.\n\nIf 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.\n\n## Rate limit\n\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Example request\n\n```\ncurl --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' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE'\n\n```\n\n## Response\n\nEntries are listed in descending order.\n\n``` json\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n  \"emails\": [\n    {\n      \"email\": \"example1@braze.com\",\n      \"hard_bounced_at\": \"2016-08-25 15:24:32 +0000\"\n    },\n    {\n      \"email\": \"example2@braze.com\",\n      \"hard_bounced_at\": \"2016-08-24 17:41:58 +0000\"\n    },\n    {\n      \"email\": \"example3@braze.com\",\n      \"hard_bounced_at\": \"2016-08-24 12:01:13 +0000\"\n    }\n  ],\n  \"message\": \"success\"\n}\n\n```"
      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'
  /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`. \n  \n\nYou can use this endpoint to set up a bi-directional sync between Braze and other email systems or your own database.\n\nTo use this endpoint, youll need to generate an API key with the `email.unsubscribe` permission.\n\n**Note:** You must provide an `end_date`, as well as either an `email` or a `start_date`.\n\nIf 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.\n\n## Rate limit\n\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Example request\n\n```\ncurl --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' \\\n--header 'Authorization: Bearer YOUR-API-KEY-HERE'\n\n```\n\n## Response\n\nEntries are listed in descending order.\n\n``` json\nContent-Type: application/json\nAuthorization: Bearer YOUR-REST-API-KEY\n{\n  \"emails\": [\n    {\n      \"email\": \"example1@braze.com\",\n      \"unsubscribed_at\": \"2016-08-25 15:24:32 +0000\"\n    },\n    {\n      \"email\": \"example2@braze.com\",\n      \"unsubscribed_at\": \"2016-08-24 17:41:58 +0000\"\n    },\n    {\n      \"email\": \"example3@braze.com\",\n      \"unsubscribed_at\": \"2016-08-24 12:01:13 +0000\"\n    }\n  ],\n  \"message\": \"success\"\n}\n\n```"
      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'
  /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). \n  \n\nYou 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.\n\nTo use this endpoint, youll need to generate an API key with the `email.status` permission.\n\n## Rate limit\n\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `email` | Required | String or array | String email address to modify, or an array of up to 50 email addresses to modify. |\n| `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'
  /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. \n  \n\nWe will also remove them from the bounce list maintained by your email provider.\n\nTo use this endpoint, youll need to generate an API key with the `email.bounce.remove` permission.\n\n## Rate limit\n\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `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'
  /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. \n  \n\nWe will also remove them from the spam list maintained by your email provider.\n\nTo use this endpoint, youll need to generate an API key with the `email.spam.remove` permission.\n\n## Rate limit\n\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `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'
  /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. \n  \n\nTo use this endpoint, youll need to generate an API key with the `email.blacklist` permission.\n\n## Rate limit\n\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `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'
  /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. \n  \n\nTo use this endpoint, youll need to generate an API key with the `email.blacklist` permission.\n\n## Rate limit\n\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits](https://www.braze.com/docs/api/api_limits/).\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `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'
components:
  responses:
    Forbidden:
      description: 403 Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 401 Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: 429 Rate Limited
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: 404 Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 400 Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: 500 Internal Server Error
      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