Iterable REST API

openapi: 3.1.0
info:
  title: Iterable REST API
  description: >-
    The Iterable REST API provides programmatic access to the Iterable
    cross-channel marketing automation platform. It exposes endpoints for
    managing users, campaigns, lists, events, commerce tracking, catalogs,
    channels, templates, experiments, workflows, and message delivery across
    email, push, SMS, and in-app channels. The API uses standard HTTP methods,
    JSON request and response bodies, and supports authentication via API keys
    or JWT-enabled keys.
  version: '1.0.0'
  contact:
    name: Iterable Support
    url: https://support.iterable.com
  termsOfService: https://iterable.com/trust/terms-of-service
externalDocs:
  description: Iterable API Documentation
  url: https://api.iterable.com/api/docs
servers:
  - 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: Campaigns
    description: >-
      Create, retrieve, and manage marketing campaigns. Access campaign
      metrics and trigger campaign sends.
  - name: Catalogs
    description: >-
      Manage product catalogs and catalog items used for personalization
      and recommendation in campaigns.
  - name: Channels
    description: >-
      Retrieve and manage messaging channels and message types used for
      organizing campaigns and templates.
  - name: Commerce
    description: >-
      Track purchase events, update cart data, and manage commerce-related
      user activity for revenue attribution.
  - name: Email
    description: >-
      Send transactional emails and manage email-specific delivery
      settings.
  - name: Events
    description: >-
      Track custom events, retrieve event data for users, and manage event
      metadata used for segmentation and campaign triggering.
  - name: Experiments
    description: >-
      Retrieve experiment configurations and metrics for A/B tests
      running across campaigns.
  - name: InApp
    description: >-
      Manage in-app messages and retrieve in-app message content for
      mobile and web clients.
  - name: Lists
    description: >-
      Create and manage subscriber lists. Subscribe and unsubscribe users
      from lists. Retrieve list metadata and membership.
  - name: MessageTypes
    description: >-
      Manage message types that categorize the kinds of messages sent
      through channels.
  - name: Metadata
    description: >-
      Store and retrieve key-value metadata tables for use in
      personalization and campaign logic.
  - name: Push
    description: >-
      Send push notifications and manage push notification delivery
      settings and tokens.
  - name: SMS
    description: >-
      Send SMS messages and manage SMS-specific delivery settings.
  - name: Templates
    description: >-
      Manage email, push, SMS, and in-app message templates. Retrieve
      template content and metadata.
  - name: Users
    description: >-
      Manage user profiles, update user fields, bulk update users, get user
      data by email or userId, and delete users.
  - name: WebPush
    description: >-
      Send web push notifications and manage web push subscription
      tokens.
  - name: Workflows
    description: >-
      Trigger workflow enrollments and manage journey-based automation
      workflows.
security:
  - apiKeyAuth: []
paths:
  /users/update:
    post:
      operationId: updateUser
      summary: Update a user profile
      description: >-
        Updates an existing user profile or creates a new one if the user does
        not already exist. Accepts user fields, email, userId, and data fields
        to set or update on the user profile.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: Successfully updated the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid API key
  /users/bulkUpdate:
    post:
      operationId: bulkUpdateUsers
      summary: Bulk update user profiles
      description: >-
        Updates multiple user profiles in a single request. Each user object in
        the array can include email, userId, and data fields to update.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - users
              properties:
                users:
                  type: array
                  description: >-
                    Array of user objects to update
                  items:
                    $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: Successfully queued bulk update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /users/{email}:
    get:
      operationId: getUserByEmail
      summary: Get a user by email
      description: >-
        Retrieves the full user profile for a given email address, including
        all data fields and subscription preferences.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/emailPath'
      responses:
        '200':
          description: User profile data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: User not found
    delete:
      operationId: deleteUserByEmail
      summary: Delete a user by email
      description: >-
        Deletes a user profile identified by email address from the Iterable
        project.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/emailPath'
      responses:
        '200':
          description: Successfully deleted user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '401':
          description: Unauthorized
        '404':
          description: User not found
  /users/byUserId/{userId}:
    get:
      operationId: getUserByUserId
      summary: Get a user by userId
      description: >-
        Retrieves the full user profile for a given userId, including all data
        fields and subscription preferences.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userIdPath'
      responses:
        '200':
          description: User profile data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: User not found
    delete:
      operationId: deleteUserByUserId
      summary: Delete a user by userId
      description: >-
        Deletes a user profile identified by userId from the Iterable project.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userIdPath'
      responses:
        '200':
          description: Successfully deleted user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '401':
          description: Unauthorized
        '404':
          description: User not found
  /users/getFields:
    get:
      operationId: getUserFields
      summary: Get user fields
      description: >-
        Retrieves all user field names and their data types defined in the
        Iterable project.
      tags:
        - Users
      responses:
        '200':
          description: List of user fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: object
                    description: >-
                      Map of field names to their data types
                    additionalProperties:
                      type: string
        '401':
          description: Unauthorized
  /users/registerDeviceToken:
    post:
      operationId: registerDeviceToken
      summary: Register a device token
      description: >-
        Registers a device token (APNs or FCM) for a user to enable push
        notification delivery.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - device
              properties:
                email:
                  type: string
                  description: >-
                    Email address of the user
                device:
                  type: object
                  description: >-
                    Device token information
                  properties:
                    token:
                      type: string
                      description: >-
                        The device token
                    platform:
                      type: string
                      enum:
                        - APNS
                        - APNS_SANDBOX
                        - GCM
                      description: >-
                        The push platform
                    applicationName:
                      type: string
                      description: >-
                        The application name
      responses:
        '200':
          description: Device token registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /events/track:
    post:
      operationId: trackEvent
      summary: Track a custom event
      description: >-
        Tracks a custom event for a user. Events can be used to trigger
        campaigns, segment users, and track user behavior within the
        Iterable platform.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackEventRequest'
      responses:
        '200':
          description: Event tracked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /events/trackBulk:
    post:
      operationId: trackBulkEvents
      summary: Track multiple events in bulk
      description: >-
        Tracks multiple custom events in a single request. Each event in the
        array includes the user identifier, event name, and associated data
        fields.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  description: >-
                    Array of events to track
                  items:
                    $ref: '#/components/schemas/TrackEventRequest'
      responses:
        '200':
          description: Events tracked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /events/{email}:
    get:
      operationId: getEventsByEmail
      summary: Get events for a user by email
      description: >-
        Retrieves events tracked for a user identified by email address.
        Supports pagination and filtering by event type.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/emailPath'
        - name: limit
          in: query
          description: >-
            Maximum number of events to return
          schema:
            type: integer
            default: 30
      responses:
        '200':
          description: List of user events
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
        '401':
          description: Unauthorized
        '404':
          description: User not found
  /campaigns:
    get:
      operationId: listCampaigns
      summary: List campaigns
      description: >-
        Retrieves metadata for all campaigns in the project associated with
        the API key. Returns campaign id, name, type, status, template
        information, and creation dates.
      tags:
        - Campaigns
      responses:
        '200':
          description: List of campaigns
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
        '401':
          description: Unauthorized
  /campaigns/create:
    post:
      operationId: createCampaign
      summary: Create a campaign
      description: >-
        Creates a new campaign in the Iterable project with the specified
        name, template, list, and configuration options.
      tags:
        - Campaigns
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreateRequest'
      responses:
        '200':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  code:
                    type: string
                  params:
                    type: object
                    properties:
                      campaignId:
                        type: integer
                        description: >-
                          The ID of the created campaign
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /campaigns/metrics:
    get:
      operationId: getCampaignMetrics
      summary: Get campaign metrics
      description: >-
        Retrieves engagement metrics for one or more campaigns, including
        sends, opens, clicks, unsubscribes, bounces, and complaints.
      tags:
        - Campaigns
      parameters:
        - name: campaignId
          in: query
          required: true
          description: >-
            One or more campaign IDs to retrieve metrics for
          schema:
            type: array
            items:
              type: integer
        - name: startDateTime
          in: query
          description: >-
            Start date for the metrics period in ISO 8601 format
          schema:
            type: string
            format: date-time
        - name: endDateTime
          in: query
          description: >-
            End date for the metrics period in ISO 8601 format
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Campaign metrics data
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Unauthorized
  /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
    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
  /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
  /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
  /channels:
    get:
      operationId: listChannels
      summary: List channels
      description: >-
        Retrieves all messaging channels configured in the Iterable project.
        Channels organize message types and are used to group campaign
        templates.
      tags:
        - Channels
      responses:
        '200':
          description: List of channels
          content:
            application/json:
              schema:
                type: object
                properties:
                  channels:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '401':
          description: Unauthorized
  /templates/email/get:
    get:
      operationId: getEmailTemplate
      summary: Get an email template
      description: >-
        Retrieves the content and metadata of an email template by its
        template ID.
      tags:
        - Templates
      parameters:
        - name: templateId
          in: query
          required: true
          description: >-
            The ID of the email template to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: Email template data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplate'
        '401':
          description: Unauthorized
        '404':
          description: Template not found
  /templates/email/update:
    post:
      operationId: updateEmailTemplate
      summary: Update an email template
      description: >-
        Updates the content and metadata of an existing email template.
      tags:
        - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateUpdate'
      responses:
        '200':
          description: Template updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /templates/push/get:
    get:
      operationId: getPushTemplate
      summary: Get a push notification template
      description: >-
        Retrieves the content and metadata of a push notification template
        by its template ID.
      tags:
        - Templates
      parameters:
        - name: templateId
          in: query
          required: true
          description: >-
            The ID of the push template to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: Push template data
          content:
            application/json:
              schema:
                type: object
                properties:
                  templateId:
                    type: integer
                  name:
                    type: string
                  message:
                    type: string
                  sound:
                    type: string
                  deeplink:
                    type: string
        '401':
          description: Unauthorized
        '404':
          description: Template not found
  /templates/sms/get:
    get:
      operationId: getSmsTemplate
      summary: Get an SMS template
      description: >-
        Retrieves the content and metadata of an SMS template by its
        template ID.
      tags:
        - Templates
      parameters:
        - name: templateId
          in: query
          required: true
          description: >-
            The ID of the SMS template to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: SMS template data
          content:
            application/json:
              schema:
                type: object
                properties:
                  templateId:
                    type: integer
                  name:
                    type: string
                  message:
                    type: string
        '401':
          description: Unauthorized
        '404':
          description: Template not found
  /templates/inApp/get:
    get:
      operationId: getInAppTemplate
      summary: Get an in-app message template
      description: >-
        Retrieves the content and metadata of an in-app message template
        by its template ID.
      tags:
        - Templates
      parameters:
        - name: templateId
          in: query
          required: true
          description: >-
            The ID of the in-app template to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: In-app template data
          content:
            application/json:
              schema:
                type: object
                properties:
                  templateId:
                    type: integer
                  name:
                    type: string
                  html:
                    type: string
        '401':
          description: Unauthorized
        '404':
          description: Template not found
  /workflows/triggerWorkflow:
    post:
      operationId: triggerWorkflow
      summary: Trigger a workflow
      description: >-
        Triggers a workflow enrollment for one or more users. The workflow
        must already be created and activated in the Iterable project.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workflowId
              properties:
                workflowId:
                  type: integer
                  description: >-
                    The ID of the workflow to trigger
                email:
                  type: string
                  description: >-
                    Email address of the user to enroll
                dataFields:
                  type: object
                  description: >-
                    Data fields to pass to the workflow
                  additionalProperties: true
                listId:
                  type: integer
                  description: >-
                    List ID to enroll all members of a list
      responses:
        '200':
          description: Workflow triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /commerce/trackPurchase:
    post:
      operationId: trackPurchase
      summary: Track a purchase event
      description: >-
        Tracks a purchase event for a user, including the items purchased,
        total value, and associated properties. Purchase data is used for
        revenue attribution and campaign triggering.
      tags:
        - Commerce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
      responses:
        '200':
          description: Purchase tracked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /commerce/updateCart:
    post:
      operationId: updateCart
      summary: Update a user's shopping cart
      description: >-
        Updates the shopping cart contents for a user. Cart data can be
        used for abandoned cart campaigns and personalization.
      tags:
        - Commerce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      description: >-
                        Email address of the user
                    userId:
                      type: string
                      description: >-
                        UserId of the user
                items:
                  type: array
                  description: >-
                    Array of cart items
                  items:
                    $ref: '#/components/schemas/CommerceItem'
      responses:
        '200':
          description: Cart updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /catalogs/{catalogName}:
    get:
      operationId: getCatalog
      summary: Get a catalog
      description: >-
        Retrieves a catalog by name, including its field definitions and
        metadata.
      tags:
        - Catalogs
      parameters:
        - $ref: '#/components/parameters/catalogNamePath'
      responses:
        '200':
          description: Catalog data
          content:
            application/json:
              schema:
                type: object
                properties:
                  params:
                    type: object
                    properties:
                      catalogName:
                        type: string
                      fieldMappings:
                        type: object
                        additionalProperties: true
        '401':
          description: Unauthorized
        '404':
          description: Catalog not found
    delete:
      operationId: deleteCatalog
      summary: Delete a catalog
      description: >-
        Deletes a catalog and all its items from the Iterable project.
      tags:
        - Catalogs
      parameters:
        - $ref: '#/components/parameters/catalogNamePath'
      responses:
        '200':
          description: Catalog deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '401':
          description: Unauthorized
        '404':
          description: Catalog not found
  /catalogs/{catalogName}/items:
    get:
      operationId: listCatalogItems
      summary: List items in a catalog
      description: >-
        Retrieves items from a catalog with support for pagination.
      tags:
        - Catalogs
      parameters:
        - $ref: '#/components/parameters/catalogNamePath'
        - name: page
          in: query
          description: >-
            Page number for pagination
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          description: >-
            Number of items per page
          schema:
            type: integer
            default: 100
      r

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/iterable/refs/heads/main/openapi/iterable-rest-api-openapi.yml