Iterable

Iterable Lists API

Create and manage subscriber lists. Subscribe and unsubscribe users from lists. Retrieve list metadata and membership.

GitHub OpenAPI

Operations 12

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/lists List all lists in the project · Get lists #
Ask an LLM
“What lists do I have in my /api project, and what's the rate limit?”
“Can I see every static and dynamic list in the project?”
Tell an agent
List all lists in my project.
Show every list from /api/lists.
POST /api/lists Create a static list with a description · Create a static list #
Ask an LLM
“Can I create a static list and give it a description?”
“How do I make a new static list via /api/lists?”
Tell an agent
Create a static list named {name}.
Create static list {name} described as {description}.
GET /api/lists/getUsers Get all users in a list · Get users in a list #
Ask an LLM
“Can I export every member of a list?”
“How slow is pulling all users from a list, given the rate limit?”
Tell an agent
Get all users in list {listId}.
Export the members of list {listId}, preferring user IDs {preferUserId}.
GET /api/lists/previewUsers Preview a random sample of list users · Preview users in a list #
Ask an LLM
“Can I see a random sample of users in a list rather than all of them?”
“What's the largest sample size for previewing a list?”
Tell an agent
Preview users in list {listId}.
Sample {size} random users from list {listId}.
POST /api/lists/subscribe Add subscribers to a list · Add subscribers to list #
Ask an LLM
“How do I add specific people to a list under /api/lists?”
“Can I add subscribers only if they already exist as users?”
Tell an agent
Add {subscribers} to list {listId}.
Subscribe {subscribers} to list {listId}, updating existing users only {updateExistingUsersOnly}.
POST /api/lists/unsubscribe Remove users from a list · Remove users from a list #
Ask an LLM
“Can I remove users from a list and also unsubscribe them from the channel?”
“Is it possible to attribute a list removal to a campaign?”
Tell an agent
Remove {subscribers} from list {listId}.
Remove {subscribers} from list {listId} and unsubscribe them from the channel {channelUnsubscribe}.
DELETE /api/lists/{listId} Delete a list · Delete a list #
Ask an LLM
“How do I delete a list I no longer need?”
“Can a list be removed by its ID?”
Tell an agent destructive · confirm first
Delete list {listId}.
Remove list {listId} from the project.
GET /api/lists/{listId}/size Count users in a list · Get count of users in list #
Ask an LLM
“How many users are on this list?”
“What's the size of a given list?”
Tell an agent
Count users in list {listId}.
Tell me the size of list {listId}.
GET /lists List subscriber lists with sizes · Get all lists #
Ask an LLM
“Is there a plain /lists endpoint that returns lists with their size and creation date?”
“Which lists exist and when was each created?”
Tell an agent
List subscriber lists from the plain /lists endpoint.
Show each list's name, size and creation date.
POST /lists Create a subscriber list (simple) · Create a list #
Ask an LLM
“Can I create a list with just a name through the basic /lists endpoint?”
“What's the minimum needed to create a subscriber list?”
Tell an agent
Create subscriber list {name} via /lists.
Make a new list called {name} with the simple endpoint.
POST /lists/subscribe Subscribe users to a list by email · Subscribe users to a list #
Ask an LLM
“Can I add users to a list by email address through the plain /lists path?”
“Which basic endpoint subscribes several emails to a list?”
Tell an agent
Using /lists/subscribe, add emails {subscribers} to list {listId}.
Subscribe {subscribers} to list {listId} with the simple endpoint.
POST /lists/unsubscribe Unsubscribe users from a list by email · Unsubscribe users from a list #
Ask an LLM
“Can I unsubscribe email addresses from a list via the plain /lists path?”
“Which basic call takes people off a subscriber list?”
Tell an agent
Using /lists/unsubscribe, remove {subscribers} from list {listId}.
Unsubscribe emails {subscribers} from list {listId} with the simple endpoint.

Documentation

📖
Documentation
https://api.iterable.com/api/docs

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/iterable/refs/heads/main/openapi/iterable-lists-api-openapi.yml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/iterable/refs/heads/main/overlays/iterable-lists-api-overlay.yaml

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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/iterable:iterable-lists-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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

iterable-lists-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Iterable Lists API
  version: '1.0'
  description: 'Operations tagged lists across 2 of this provider''s published API definitions: iterable-api-openapi.json, iterable-rest-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.iterable.com/
- url: https://api.iterable.com/api
  description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
  description: European Data Center (EDC)
tags:
- name: Lists
paths:
  /api/lists:
    get:
      description: 'Get all lists within a project. Rate limit: 100 requests/second, per project.'
      operationId: getLists
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetListsResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
      summary: Get lists
      tags:
      - Lists
      security:
      - api_key: []
    post:
      description: Create a new static list.
      operationId: create
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateListResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
      summary: Create a static list
      tags:
      - Lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateListRequest'
        description: name and optional description
        required: true
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/lists/getUsers:
    get:
      description: 'Get all users within a list. Rate limit: 5 requests/minute, per project.'
      operationId: getUsers
      parameters:
      - description: list id
        in: query
        name: listId
        required: true
        schema:
          type: integer
          format: int64
      - description: If true, will return the userId instead of email if both exists in a user profile for a hybrid project.
        in: query
        name: preferUserId
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
        '503':
          description: Request timeout.  Try again later.
      summary: Get users in a list
      tags:
      - Lists
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/lists/previewUsers:
    get:
      description: 'Get a random sample of up to 5000 users within a list. Rate limit: 5 requests/minute, per project.'
      operationId: getUsersPreview
      parameters:
      - description: list id
        in: query
        name: listId
        required: true
        schema:
          type: integer
          format: int64
      - description: If true, will return the userId instead of email if both exists in a user profile for a hybrid project.
        in: query
        name: preferUserId
        required: false
        schema:
          type: boolean
          default: false
      - description: Number of users the response will return, up to 5000. Defaults to 1000.
        in: query
        name: size
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
        '503':
          description: Request timeout.  Try again later.
      summary: Preview users in a list
      tags:
      - Lists
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/lists/subscribe:
    post:
      description: 'Add specific subscribers to a list.


        Learn about identifying users by userId and email.'
      operationId: subscribe
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBulkUpdateListResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
      summary: Add subscribers to list
      tags:
      - Lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeRequest'
        description: email list id and list of emails
        required: true
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/lists/unsubscribe:
    post:
      description: 'Remove specific users from a list.


        Learn about identifying users by userId and email.'
      operationId: unsubscribe
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBulkUpdateListResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
      summary: Remove users from a list
      tags:
      - Lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnsubscribeRequest'
        description: email list id and list of emails
        required: true
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/lists/{listId}:
    delete:
      description: Delete a list by listId.
      operationId: delete
      parameters:
      - description: list id
        in: path
        name: listId
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableApiResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
        '409':
          description: List is in use
      summary: Delete a list
      tags:
      - Lists
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/lists/{listId}/size:
    get:
      description: 'Get the number of users within a list. Rate limit: 5 requests/minute, per project.'
      operationId: getListCount
      parameters:
      - description: list id
        in: path
        name: listId
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
        '503':
          description: Request timeout.  Try again later.
      summary: Get count of users in list
      tags:
      - Lists
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /lists:
    get:
      operationId: listLists
      summary: Get all lists
      description: Retrieves all subscriber lists in the Iterable project, including list ID, name, creation date, and size.
      tags:
      - Lists
      responses:
        '200':
          description: List of subscriber lists
          content:
            application/json:
              schema:
                type: object
                properties:
                  lists:
                    type: array
                    items:
                      $ref: '#/components/schemas/List'
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
    post:
      operationId: createList
      summary: Create a list
      description: Creates a new subscriber list in the Iterable project.
      tags:
      - Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the new list
      responses:
        '200':
          description: List created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  listId:
                    type: integer
                    description: The ID of the created list
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
    servers:
    - url: https://api.iterable.com/api
      description: US Data Center (USDC)
    - url: https://api.eu.iterable.com/api
      description: European Data Center (EDC)
  /lists/subscribe:
    post:
      operationId: subscribeToList
      summary: Subscribe users to a list
      description: Adds one or more users to a subscriber list. Users are identified by email address.
      tags:
      - Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - listId
              - subscribers
              properties:
                listId:
                  type: integer
                  description: The ID of the list to subscribe users to
                subscribers:
                  type: array
                  description: Array of subscriber objects
                  items:
                    type: object
                    properties:
                      email:
                        type: string
                        description: Email address of the user to subscribe
                      userId:
                        type: string
                        description: UserId of the user to subscribe
                      dataFields:
                        type: object
                        description: Optional data fields to set on the user
                        additionalProperties: true
      responses:
        '200':
          description: Users subscribed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  successCount:
                    type: integer
                  failCount:
                    type: integer
                  invalidEmails:
                    type: array
                    items:
                      type: string
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
    servers:
    - url: https://api.iterable.com/api
      description: US Data Center (USDC)
    - url: https://api.eu.iterable.com/api
      description: European Data Center (EDC)
  /lists/unsubscribe:
    post:
      operationId: unsubscribeFromList
      summary: Unsubscribe users from a list
      description: Removes one or more users from a subscriber list. Users are identified by email address.
      tags:
      - Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - listId
              - subscribers
              properties:
                listId:
                  type: integer
                  description: The ID of the list to unsubscribe users from
                subscribers:
                  type: array
                  description: Array of subscriber objects
                  items:
                    type: object
                    properties:
                      email:
                        type: string
                        description: Email address of the user to unsubscribe
      responses:
        '200':
          description: Users unsubscribed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  successCount:
                    type: integer
                  failCount:
                    type: integer
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
    servers:
    - url: https://api.iterable.com/api
      description: US Data Center (USDC)
    - url: https://api.eu.iterable.com/api
      description: European Data Center (EDC)
components:
  schemas:
    OptionalApiUser:
      properties:
        dataFields:
          type: object
        email:
          description: An email address that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
          type: string
        mergeNestedObjects:
          description: Merge top-level objects instead of overwriting them. Defaults to <code>false</code>. For example, if a user profile has data <code>{"mySettings":{"mobile":true}}</code> and the request has data <code>{"mySettings":{"email":true}}</code>, merging results in <code>{"mySettings":{"mobile":true,"email":true}}</code>.
          example: false
          type: boolean
        preferUserId:
          description: Whether or not a new user should be created if the request includes a <code>userId</code> that doesn't yet exist in the Iterable project. Defaults to <code>false</code>. Only respected in API calls for <a href="https://support.iterable.com/hc/articles/29156459027348">email-based projects</a>.
          example: false
          type: boolean
        userId:
          description: A user ID that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
          type: string
      type: object
    UnsubscribeRequest:
      properties:
        campaignId:
          description: attribute unsubscribe to a campaign
          format: int64
          type: integer
        channelUnsubscribe:
          description: 'Unsubscribe email from list''s associated channel - essentially a global unsubscribe. (default: false)'
          type: boolean
        listId:
          format: int64
          type: integer
        subscribers:
          items:
            $ref: '#/components/schemas/Unsubscriber'
          type: array
      required:
      - listId
      - subscribers
      type: object
    IterableApiResponse:
      properties:
        code:
          enum:
          - Success
          - BadApiKey
          - BadAuthorizationHeader
          - BadJsonBody
          - BadParams
          - BatchTooLarge
          - DatabaseError
          - EmailAlreadyExists
          - ExternalKeyConflict
          - Forbidden
          - ForbiddenParamsError
          - ForgottenUserError
          - GenericError
          - InvalidEmailAddressError
          - InvalidJwtPayload
          - InvalidUserIdError
          - JwtUserIdentifiersMismatched
          - NotFound
          - QueueEmailError
          - RateLimitExceeded
          - RequestFieldsTypesMismatched
          - Unauthorized
          - UniqueFieldsLimitExceeded
          - UnknownEmailError
          - UnknownUserIdError
          - UserIdAlreadyExists
          type: string
        msg:
          description: Response description
          type: string
        params:
          description: Additional info
          type: object
      required:
      - code
      - msg
      type: object
    CreateListRequest:
      properties:
        description:
          type: string
        name:
          type: string
      required:
      - name
      type: object
    SubscribeRequest:
      properties:
        listId:
          format: int64
          type: integer
        subscribers:
          items:
            $ref: '#/components/schemas/OptionalApiUser'
          type: array
        updateExistingUsersOnly:
          description: Whether to skip operation when the request includes a <code>userId</code> or <code>email</code> that doesn't yet exist in the Iterable project. When <code>true</code>, Iterable ignores requests with unknown userIds and email addresses. When <code>false</code>, Iterable creates new users. Defaults to <code>false</code>. Only respected in API calls for <a href="https://support.iterable.com/hc/articles/29156459027348">userID-based and hybrid projects</a>.
          example: false
          type: boolean
      required:
      - listId
      - subscribers
      type: object
    Unsubscriber:
      properties:
        email:
          description: An email address that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
          type: string
        userId:
          description: A user ID that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
          type: string
      type: object
    ListDetails:
      properties:
        createdAt:
          description: Creation timestamp as epoch time in milliseconds
          format: int32
          type: integer
        description:
          type: string
        id:
          format: int64
          type: integer
        isGlobalSuppressionEnabled:
          description: Indicates if the suppression list is global. This field is only present for lists where <code>listType</code> is <code>Suppression</code>. <code>true</code> indicates a global suppression list; <code>false</code> indicates a standard suppression list.
          type: boolean
        listType:
          enum:
          - Standard
          - Dynamic
          - Suppression
          - Internal
          type: string
        name:
          type: string
      required:
      - createdAt
      - id
      - listType
      - name
      type: object
    CreateListResponse:
      properties:
        listId:
          format: int64
          type: integer
      required:
      - listId
      type: object
    UserBulkUpdateListResponse:
      properties:
        createdFields:
          description: Fields that were created because <code>createNewFields</code> was <code>true</code> or <code>createNewFields</code> was not set and the project is configured to add unrecognized user profile fields.
          items:
            type: string
          type: array
          uniqueItems: true
        failCount:
          description: Number of user profiles that could not be updated. See <code>failedUpdates</code> for more details.
          format: int32
          type: integer
        failedUpdates:
          $ref: '#/components/schemas/FailedUserUpdates'
          description: Details about failed updates.
        filteredOutFields:
          description: Fields that were dropped because <code>createNewFields</code> was <code>false</code> or <code>createNewFields</code> was not set and the project is configured to drop unrecognized user profile fields.
          items:
            type: string
          type: array
          uniqueItems: true
        invalidEmails:
          description: <code>email</code> addresses of users that failed to update. This field is deprecated — use <code>failedUpdates</code> instead.
          items:
            type: string
          type: array
        invalidUserIds:
          description: <code>userId</code> values of users that failed to update. This field is deprecated — use <code>failedUpdates</code> instead.
          items:
            type: string
          type: array
        successCount:
          description: Number of user profiles that were updated in response to the request.
          format: int32
          type: integer
      required:
      - failCount
      - successCount
      type: object
    GetListsResponse:
      properties:
        lists:
          items:
            $ref: '#/components/schemas/ListDetails'
          type: array
      required:
      - lists
      type: object
    FailedUserUpdates:
      properties:
        conflictEmails:
          description: Existing <code>email</code> addresses that prevented identity updates for users in the request.
          items:
            type: string
          type: array
        conflictUserIds:
          description: Existing <code>userId</code> values that prevented identity updates for users in the request.
          items:
            type: string
          type: array
        forgottenEmails:
          description: <code>email</code> addresses of users that were not updated because they've been GDPR forgotten.
          items:
            type: string
          type: array
        forgottenUserIds:
          description: <code>userId</code> values of users that were not updated because they've been GDPR forgotten.
          items:
            type: string
          type: array
        invalidDataEmails:
          description: <code>email</code> addresses of users that were not updated because of invalid data in <code>dataFields</code> other than an invalid <code>email</code> or <code>userId</code>.
          items:
            type: string
          type: array
        invalidDataUserIds:
          description: <code>userId</code> values of users that were not updated because of invalid data in <code>dataFields</code> other than an invalid <code>email</code> or <code>userId</code>.
          items:
            type: string
          type: array
        invalidEmails:
          description: Malformed <code>email</code> addresses found either at the top level of a passed-in user object, or in <code>dataFields</code>.
          items:
            type: string
          type: array
        invalidUserIds:
          description: 'Malformed <code>userId</code> values (e.g. empty, too long, or containing non-ASCII or non-printable characters or a trailing space) found either at the top level of a passed-in user object, or in <code>dataFields</code>. '
          items:
            type: string
          type: array
        notFoundEmails:
          description: <code>email</code> addresses that were not found (for subscribe/unsubscribe only).
          items:
            type: string
          type: array
        notFoundUserIds:
          description: <code>userId</code> values that were not found (for subscribe/unsubscribe only).
          items:
            type: string
          type: array
      type: object
    List:
      type: object
      description: A subscriber list in Iterable
      properties:
        id:
          type: integer
          description: List ID
        name:
          type: string
          description: List name
        createdAt:
          type: string
          format: date-time
          description: List creation date
        listType:
          type: string
          description: Type of list
        description:
          type: string
          description: List description
  securitySchemes:
    api_key:
      in: header
      name: Api-Key
      type: apiKey
    apiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: Iterable API key passed in the Api-Key header. API keys can be created and managed in the Iterable project settings.
externalDocs:
  description: Iterable API Documentation
  url: https://api.iterable.com/api/docs
x-refined-from:
- iterable-api-openapi.json
- iterable-rest-api-openapi.yml