Optimizely Recipients API

openapi: 3.2.0
info:
  title: Optimizely Recipients API
  version: '1.0'
  description: 'Operations tagged Recipients across 2 of this provider''s published API definitions: optimizely-campaign-openapi.yml, optimizely-campaign-optimizely-campaign-rest-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.campaign.episerver.net/rest
  description: Optimizely Campaign Production Server
tags:
- name: Recipients
  description: Manage recipients and recipient lists for email campaigns.
paths:
  /{clientId}/recipients/{recipientListId}:
    get:
      operationId: listRecipients
      summary: List recipients
      description: Returns a list of recipients from the specified recipient list.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/clientId'
      - $ref: '#/components/parameters/recipientListId'
      responses:
        '200':
          description: Successfully retrieved recipients
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recipient'
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Recipient list not found
      security:
      - basicAuth: []
    post:
      operationId: addRecipient
      summary: Add a recipient
      description: Adds a new recipient to the specified recipient list.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/clientId'
      - $ref: '#/components/parameters/recipientListId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientInput'
      responses:
        '201':
          description: Recipient successfully added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '400':
          description: Invalid request body
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Recipient list not found
      security:
      - basicAuth: []
    put:
      tags:
      - Recipients
      summary: Add multiple recipients to a recipient list. Double opt-in processes will not be overwritten by other opt-in processes (see <a href="https://support.optimizely.com/hc/en-us/articles/4413192291981#prioritization">Opt-in documentation</a>).
      operationId: addRecipients
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecipientsRequestData'
      responses:
        '200':
          description: Adding recipients was initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestRecipientsCreationModify'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                $ref: '#/components/schemas/RestRecipientsCreationModify'
        '409':
          description: The indicated opt-in process is not suitable for adding recipients.
      security:
      - Authorization: []
    delete:
      tags:
      - Recipients
      summary: Delete recipients from a recipient list
      description: 'Delete multiple recipients from a recipient list. <b>Note</b>: All recipients are deleted if neither "recipientIds" nor "removalType" is specified.'
      operationId: deleteRecipients
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: recipientIds
        in: query
        description: Comma-separated list of recipient IDs. Cannot be combined with 'removalType' parameter.
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: removalType
        in: query
        description: Specifies the recipients to be removed. Cannot be combined with 'recipientIds' parameter.
        schema:
          type: string
          enum:
          - blacklisted
          - bounced
          - unsubscribed
      - name: mediaType
        in: query
        description: Filter recipients for a given type (can only be used with 'removalType' parameter)
        schema:
          type: string
          enum:
          - EMAIL
          - FAX
          - SMS
          - LETTER
          - PUSH
          - PRINT
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: The deletion was initiated successfully.
        '400':
          description: The parameters "recipientIds" and "removalType" were added simultaneously. Provide either "recipientIds" or "removalType" parameter.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
      description: Optimizely Campaign Production Server
  /{clientId}/recipients/{recipientListId}/{recipientId}:
    get:
      operationId: getRecipient
      summary: Get a recipient
      description: Retrieves the details of a specific recipient from a recipient list.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/clientId'
      - $ref: '#/components/parameters/recipientListId'
      - $ref: '#/components/parameters/recipientId'
      responses:
        '200':
          description: Successfully retrieved the recipient
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Recipient not found
      security:
      - basicAuth: []
    put:
      operationId: updateRecipient
      summary: Update a recipient
      description: Updates the specified recipient with the provided fields.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/clientId'
      - $ref: '#/components/parameters/recipientListId'
      - $ref: '#/components/parameters/recipientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientInput'
      responses:
        '200':
          description: Recipient successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '400':
          description: Invalid request body
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Recipient not found
      security:
      - basicAuth: []
    delete:
      operationId: deleteRecipient
      summary: Delete a recipient
      description: Removes a recipient from the specified recipient list.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/clientId'
      - $ref: '#/components/parameters/recipientListId'
      - $ref: '#/components/parameters/recipientId'
      responses:
        '204':
          description: Recipient successfully deleted
        '401':
          description: Authentication credentials are missing or invalid
        '404':
          description: Recipient not found
      security:
      - basicAuth: []
    post:
      tags:
      - Recipients
      summary: Update attribute values of a recipient
      operationId: modifyRecipientAttributes
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: recipientId
        in: path
        description: Recipient ID (usually the email address)
        required: true
        schema:
          type: string
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ModifyRecipientAttributesRequestData'
      responses:
        '200':
          description: The recipient's attributes were updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestRecipient'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                $ref: '#/components/schemas/RestRecipient'
        '409':
          description: The indicated recipient list is not assigned to the indicated client. Ensure that "clientId" and "recipientListId" are correct and that the "recipientListId" is assigned to the indicated client.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
      description: Optimizely Campaign Production Server
  /{clientId}/recipients/{recipientListId}/count:
    get:
      tags:
      - Recipients
      summary: Get the total number of recipients in a recipient list
      description: '<b>Request limit:</b> In total, a maximum of 10 simultaneous requests for the following operations are permitted per client: REST API countRecipients, <a href="https://api.campaign.episerver.net/apidoc/index.html#/Recipients/selectRecipients" target="_blank">REST API selectRecipients</a> and <a href="https://world.episerver.com/documentation/developer-guides/campaign/SOAP-API/recipientwebservice/getcount/" target="_blank">SOAP API getCount (RecipientWebservice)</a>.'
      operationId: countRecipients
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: targetGroup
        in: query
        description: Target group ID
        schema:
          type: integer
          format: int64
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: The number of recipients was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestCount'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                $ref: '#/components/schemas/RestCount'
        '429':
          description: Too many requests are used at the same time to retrieve recipients.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
  /{clientId}/recipients/{recipientListId}/distinctvalues/count:
    get:
      tags:
      - Recipients
      summary: Get the total number of recipients for distinct attribute values
      description: Get all distinct attribute values and count the recipients for each value.
      operationId: countDistinctValues
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: string
      - name: targetGroup
        in: query
        description: Target group ID
        schema:
          type: integer
          format: int64
      - name: attributeName
        in: query
        description: Field name (e.g. firstname, lastname etc.) to be retrieved for distinct values
        required: true
        schema:
          type: string
      - name: threshold
        in: query
        description: Number of characters that are examined
        schema:
          type: integer
          format: int32
          default: 100000
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: The recipient number was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestAttributeValuesWithCount'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                $ref: '#/components/schemas/RestAttributeValuesWithCount'
        '400':
          description: Attribute name is not provided or attribute name does not exist in current recipient list
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
  /{clientId}/recipients/{recipientListId}/distinctvalues:
    get:
      tags:
      - Recipients
      summary: Get all distinct attribute values of a recipient
      operationId: retrieveDistinctValues
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: string
      - name: targetGroup
        in: query
        description: Target group ID
        schema:
          type: integer
          format: int64
      - name: attributeName
        in: query
        description: Field name (e.g. firstname, lastname etc.) to be retrieved for distinct values
        required: true
        schema:
          type: string
      - name: threshold
        in: query
        description: Number of characters that are examined
        schema:
          type: integer
          format: int32
          default: 100000
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: The distinct values were retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestAttributeValues'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                $ref: '#/components/schemas/RestAttributeValues'
        '400':
          description: Attribute name is not provided or attribute name does not exist in current recipient list
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
  /{clientId}/recipients/{recipientListId}/modify:
    put:
      tags:
      - Recipients
      summary: Update attribute values of multiple recipients
      operationId: modifyRecipientsAttributes
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRecipientsRequestData'
      responses:
        '200':
          description: The recipients' attributes were updated. The IDs of recipients for which attributes could not be updated are displayed as failedIds in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestRecipientsCreationModify'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                $ref: '#/components/schemas/RestRecipientsCreationModify'
      security:
      - Authorization: []
    post:
      tags:
      - Recipients
      summary: Update attribute values of recipients filtered by a target group
      operationId: modifyRecipientsAttributesByTargetGroup
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ModifyRecipientsAttributesRequestData'
      responses:
        '200':
          description: The recipient's attributes were updated.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RestRecipient'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RestRecipient'
        '400':
          description: The target group is not provided or recipient's attribute is not recognized or its value cannot be parsed. Ensure that "target group" is added to the request and that the required parameters are correct.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
  /{clientId}/recipients/{recipientListId}/{recipientId}/optinstatus:
    get:
      tags:
      - Recipients
      summary: Check status optin of given recipient
      description: Check whether a recipient is opted in or not
      operationId: getOptinStatus
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: recipientId
        in: path
        description: Recipient ID (usually the email address)
        required: true
        schema:
          type: string
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: The recipient's optin status was retrieved successfully.
          content:
            application/json:
              schema:
                type: string
            application/vnd.optivo.broadmail.v1+json:
              schema:
                type: string
        '400':
          description: The recipient list is not of type opt-in
        '404':
          description: The recipient could not be found. Ensure that the required parameters such as "recipientId" and "recipientListId" are correct and the recipient exists.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
  /{clientId}/recipients/{recipientListId}/{recipientId}/valid:
    get:
      tags:
      - Recipients
      summary: Check whether a recipient is valid
      description: Check if a recipient can receive mailings. Recipients are valid if they are not blacklisted, not unsubscribed and did not exceed the bounce limit.
      operationId: isRecipientValid
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: mediaType
        in: query
        description: 'Media type <p><i>Default value</i> : EMAIL</p>'
        schema:
          type: string
          enum:
          - EMAIL
          - FAX
          - SMS
          - LETTER
          - PUSH
          - PRINT
      - name: recipientId
        in: path
        description: Recipient ID (usually the email address)
        required: true
        schema:
          type: string
      - name: recipientListId
        in: path
        description: Recipient list ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: The recipient's validation result was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestRecipientValid'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                $ref: '#/components/schemas/RestRecipientValid'
        '404':
          description: The recipient could not be found. Ensure that the required parameters such as "recipientId" and "recipientListId" are correct and the recipient exists.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
  /{clientId}/recipients/trackingoptout:
    post:
      tags:
      - Recipients
      summary: Create a tracking opt-out
      description: Create a tracking opt-out to deactivate the tracking of action-based data (opens and clicks) of a recipient.
      operationId: createTrackingOptOut
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RecipientBasedRequestData'
      responses:
        '201':
          description: The tracking opt-out was created.
        '406':
          description: The tracking opt-out is not activated for this client. Ensure that the 'clientId' is correct and the required feature is enabled in the indicated client.
      security:
      - Authorization: []
    delete:
      tags:
      - Recipients
      summary: Delete a tracking opt-out
      description: Delete a tracking opt-out to reactivate the tracking of action-based data (opens and clicks) of a recipient.
      operationId: deleteTrackingOptOut
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: string
      - name: recipientId
        in: query
        description: Recipient ID (usually the email address)
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The tracking opt-out was deleted.
        '406':
          description: The tracking opt-out is not activated for this client. Ensure that the 'clientId' is correct and the required feature is enabled in the indicated client.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
  /{clientId}/recipients:
    get:
      tags:
      - Recipients
      summary: Check whether a recipient is valid in multiple recipient lists
      description: Check if a recipient can receive mailings in multiple recipient lists. Recipients are valid if they are not blacklisted, not unsubscribed and did not exceed the bounce limit.
      operationId: isRecipientValid_1
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: recipientListIds
        in: query
        description: Comma-separated list of recipient list IDs <p><b>Note:</b> If you do not specify a recipient list ID or the recipient list ID is invalid or does not exist, the response body will be empty.</p>
        schema:
          type: array
          items:
            type: integer
            format: int64
      - name: recipientId
        in: query
        description: Recipient ID (usually the email address)
        required: true
        schema:
          type: string
      - name: mediaType
        in: query
        description: Media type
        schema:
          type: string
          default: EMAIL
          enum:
          - EMAIL
          - FAX
          - SMS
          - LETTER
          - PUSH
          - PRINT
      responses:
        '200':
          description: The recipient's validation result was retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RestRecipientValid'
            application/vnd.optivo.broadmail.v1+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RestRecipientValid'
        '400':
          description: The required parameter 'recipientId' is not provided.
      security:
      - Authorization: []
    delete:
      tags:
      - Recipients
      summary: Delete the recipient history
      description: Delete all action data of a recipient.
      operationId: wipeRecipientHistory
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      - name: reason
        in: query
        description: Reason for deletion
        schema:
          type: string
      - name: recipientKey
        in: query
        description: Recipient key (that is, the recipient ID)
        required: true
        schema:
          type: string
      responses:
        '202':
          description: The recipient history deletion was initiated successfully.
        '400':
          description: The required parameter 'recipientKey' is not provided. Check for the recipient key (that is, the recipient ID) and add it to the request.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
  /{clientId}/recipients/updaterecipientid:
    post:
      tags:
      - Recipients
      summary: Update a recipient ID
      operationId: updateRecipientId
      parameters:
      - name: clientId
        in: path
        description: Client ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateRecipientIdRequestData'
      responses:
        '200':
          description: The recipient ID was updated successfully.
        '400':
          description: Recipient ID update is not possible because of a general error.
      security:
      - Authorization: []
    servers:
    - url: https://api.campaign.episerver.net/rest
components:
  parameters:
    clientId:
      name: clientId
      in: path
      required: true
      description: The unique identifier for the Optimizely Campaign client
      schema:
        type: string
    recipientListId:
      name: recipientListId
      in: path
      required: true
      description: The unique identifier for the recipient list
      schema:
        type: integer
        format: int64
    recipientId:
      name: recipientId
      in: path
      required: true
      description: The unique identifier for the recipient
      schema:
        type: integer
        format: int64
  schemas:
    RecipientInput:
      type: object
      description: Input for creating or updating a recipient
      required:
      - email
      properties:
        email:
          type: string
          format: email
          description: Email address of the recipient
        first_name:
          type: string
          description: First name of the recipient
        last_name:
          type: string
          description: Last name of the recipient
        custom_fields:
          type: object
          description: Custom fields associated with the recipient
          additionalProperties:
            type: string
    Recipient:
      type: object
      description: A recipient in a mailing list
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the recipient
        email:
          type: string
          format: email
          description: Email address of the recipient
        first_name:
          type: string
          description: First name of the recipient
        last_name:
          type: string
          description: Last name of the recipient
        status:
          type: string
          description: Subscription status of the recipient
          enum:
          - active
          - unsubscribed
          - bounced
        custom_fields:
          type: object
          description: Custom fields associated with the recipient
          additionalProperties:
            type: string
        created:
          type: string
          format: date-time
          description: Timestamp when the recipient was created
        last_modified:
          type: string
          format: date-time
          description: Timestamp when the recipient was last modified
    RestRecipientsCreationModify:
      type: object
      properties:
        count:
          type: integer
          format: int32
        failedIds:
          type: array
          items:
            type: string
    RestRecipient:
      type: object
      properties:
        id:
          type: string
          description: Recipient ID
        created:
          type: string
          description: Creation date
          format: date-time
        modified:
          type: string
          description: Modification date
          format: date-time
        optInMailId:
          type: string
          description: Mail ID in case of double/confirmed opt-in process
        links:
          type: array
          description: Restful links
          items:
            type: object
            properties:
              uriBuilder:
                type: object
              rels:
                type: array
                items:
                  type: string
              rel:
                type: string
              type:
                type: string
              params:
                type: object
                additionalProperties:
                  type: string
              title:
                type: string
              uri:
                type: string
                format: uri
            description: Restful links
    RecipientBasedRequestData:
      required:
      - recipientId
      type: object
      properties:
        recipientId:
          type: string
          description: Recipient ID (usually the email address)
    CreateRecipientRequestData:
      required:
      - recipientId
      type: object
      properties:
        returnOptInMailId:
          type: boolean
          description: Retrieve the mail ID for an opt-in process of type "double" or "confirmed"
          default: false
        address:
          type: string
          description: Address of the recipient. Required if ID attribute differs from the address.
        data:
          type: string
          description: Recipient data. Configure "data.[attribute]" according to the corresponding recipient list field.<p>Does not work with the "Try it out" feature.</p>
        optinProcessId:
          type: integer
          description: ID of the opt-in process
          format: int64
        recipientId:
          type: string
          description: Recipient ID (usually the email address)
    UpdateRecipientsRequestData:
      type: object
      properties:
        updateMode:
          type: string
          enum:
          - set
          - prepend
          - append
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient_2'
    RestCount:
      type: object
      properties:
        links:
          type: array
          items:
            type: object
            properties:
              uriBuilder:
                type: object
              rels:
                type: array
                items:
                  type: string
              rel:
                type: string
              type:
                type: string
              params:
                type: object
                additionalProperties:
                  type: string
              title:
                type: string
              uri:
                type: string
                format: uri
        count:
          type: integer
          description: Total number
          format: int64
    RestAttributeValues:
      type: object
      properties:
        attributeValues:
          type: array
          items:
            type: object
        links:
          type: array
          

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