openapi: 3.1.0
info:
  title: Lists / Address books
  version: 2.0.2
  description: 'Manage contact lists (address books) and their memberships. Use this API to create, update, and delete lists; retrieve all, public, or private lists; bulk-import contacts; remove individual or multiple contacts; manage subscription status (unsubscribe and resubscribe); and query contacts within a list by preference opt-in status or unsubscribe date.

    '
x-readme:
  headers: []
  explorer-enabled: true
  proxy-enabled: true
x-readme-fauxas: true
x-samples-languages:
- curl
- csharp
- java
- javascript
- node
- python
- php
- ruby
externalDocs:
  description: Learn more about Dotdigital APIs
  url: https://developer.dotdigital.com
servers:
- url: https://{region}-api.dotdigital.com
  variables:
    region:
      default: r1
      enum:
      - r1
      - r2
      - r3
      description: The Dotdigital region id your account belongs to
security:
- basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
paths:
  /v2/address-books/{id}/campaigns:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get campaigns sent to address book or segment
      deprecated: false
      description: Gets any campaigns that have been sent to an address book or a segment
      operationId: get-campaigns-sent-to-address-book-or-segment
      tags:
      - Lists / Address books
      parameters:
      - name: id
        in: path
        description: The ID of the address book or segment
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: select
        in: query
        description: he select parameter requires a number between 1 and 1000 (0 is not a valid number). You may only select a maximum of 1000 results in a single request. This parameter goes within the URL.
        required: false
        schema:
          type: integer
          format: int32
      - name: skip
        in: query
        description: The skip parameter should be used in tandem with the select parameter when wanting to iterate through a whole data set. If you want to select the next 1000 records you should set the select parameter to 1000 and the skip parameter to 1000, which will return records 1001 to 2000. You should continue to do this until 0 records are returned to retrieve the whole data set.
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 1
                    name:
                      type: string
                      examples:
                      - Monthly newsletter Dec 2015
                    subject:
                      type: string
                      examples:
                      - Monthly newsletter
                    fromName:
                      type: string
                      examples:
                      - Company name
                    fromAddress:
                      type: object
                      properties:
                        id:
                          type: integer
                          default: 0
                          examples:
                          - 1
                        email:
                          type: string
                          examples:
                          - demo@apiconnector.com
                    htmlContent: {}
                    plainTextContent: {}
                    replyAction:
                      type: string
                      examples:
                      - Unset
                    replyToAddress: {}
                    isSplitTest:
                      type: boolean
                      default: true
                      examples:
                      - false
                    status:
                      type: string
                      examples:
                      - Sent
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 1
                    name: Monthly newsletter Dec 2015
                    subject: Monthly newsletter
                    fromName: Company name
                    fromAddress:
                      id: 1
                      email: demo@apiconnector.com
                    htmlContent: null
                    plainTextContent: null
                    replyAction: Unset
                    replyToAddress: null
                    isSplitTest: false
                    status: Sent
                  - id: 4
                    name: New product promotion
                    subject: New product!
                    fromName: Company name
                    fromAddress:
                      id: 1
                      email: demo@apiconnector.com
                    htmlContent: null
                    plainTextContent: null
                    replyAction: WebMailForward
                    replyToAddress: demo@apiconnector.com
                    isSplitTest: false
                    status: Sent
  /v2/address-books:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    post:
      summary: Create list
      deprecated: false
      description: Creates an list / address book
      operationId: create-address-book
      tags:
      - Lists / Address books
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the address book. (max 128 characters)
                  maxLength: 128
                visibility:
                  type: string
                  description: All address books are created as 'Private' by default but you can set it as 'Public' upon creation should you wish to.
                  default: Private
                  enum:
                  - Private
                  - Public
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  name:
                    type: string
                    examples:
                    - My Address Book
                  visibility:
                    type: string
                    examples:
                    - Public
                  contacts:
                    type: integer
                    default: 0
                    examples:
                    - 0
              examples:
                Result:
                  summary: Result
                  value:
                    id: 1
                    name: My Address Book
                    visibility: Public
                    contacts: 0
    get:
      summary: Get lists
      deprecated: false
      description: Gets all lists / address books
      operationId: get-address-books
      tags:
      - Lists / Address books
      parameters:
      - name: select
        in: query
        description: The number of records to select between 1 and 1000
        required: false
        schema:
          type: integer
          format: int32
      - name: skip
        in: query
        description: The numbers of records to skip in the result set
        required: false
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 1
                    name:
                      type: string
                      examples:
                      - Address book 1
                    visibility:
                      type: string
                      examples:
                      - Private
                    contacts:
                      type: integer
                      default: 0
                      examples:
                      - 5
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 1
                    name: Address book 1
                    visibility: Private
                    contacts: 5
                  - id: 2
                    name: Address book 2
                    visibility: Public
                    contacts: 7
                  - id: 3
                    name: Address book 3
                    visibility: Private
                    contacts: 7
                  - id: 4
                    name: Address book 4
                    visibility: Public
                    contacts: 6
  /v2/address-books/{id}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    delete:
      summary: Delete list
      deprecated: false
      description: Deletes an list / address book by id
      operationId: delete-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: id
        in: path
        description: The ID of the list / address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      responses:
        '204':
          description: '204'
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                Result:
                  summary: Result
                  value: {}
    put:
      summary: Update list
      deprecated: false
      description: Updates an list / address book by id
      operationId: update-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: id
        in: path
        description: The ID of the address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the address book. (max 128 characters)
                visibility:
                  type: string
                  description: All address books are created as 'Private' by default but you can set it as 'Public' upon creation should you wish to.
                  default: Private
                  enum:
                  - Private
                  - Public
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  name:
                    type: string
                    examples:
                    - My Updated Address Book
                  visibility:
                    type: string
                    examples:
                    - Private
                  contacts:
                    type: integer
                    default: 0
                    examples:
                    - 0
              examples:
                Result:
                  summary: Result
                  value:
                    id: 1
                    name: My Updated Address Book
                    visibility: Private
                    contacts: 0
    get:
      summary: Get list
      deprecated: false
      description: This operation retrieves an list / address book by its id
      operationId: get-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: id
        in: path
        description: The ID of the list / address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 2
                  name:
                    type: string
                    examples:
                    - Address book 2
                  visibility:
                    type: string
                    examples:
                    - Private
                  contacts:
                    type: integer
                    default: 0
                    examples:
                    - 5
              examples:
                Result:
                  summary: Result
                  value:
                    id: 2
                    name: Address book 2
                    visibility: Private
                    contacts: 5
  /v2/address-books/private:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get private lists
      deprecated: false
      description: Gets all private lists / address books
      operationId: get-private-address-books
      tags:
      - Lists / Address books
      parameters:
      - name: limit
        in: query
        description: The number of records to select between 1 and 1000
        required: false
        schema:
          type: integer
          format: int32
      - name: skip
        in: query
        description: The numbers of records to skip in the result set
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 2
                    name:
                      type: string
                      examples:
                      - Address book 2
                    visibility:
                      type: string
                      examples:
                      - Private
                    contacts:
                      type: integer
                      default: 0
                      examples:
                      - 5
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 2
                    name: Address book 2
                    visibility: Private
                    contacts: 5
                  - id: 3
                    name: Address book 3
                    visibility: Private
                    contacts: 7
  /v2/address-books/public:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get public lists
      deprecated: false
      description: Gets all public lists / address books
      operationId: get-public-address-books
      tags:
      - Lists / Address books
      parameters:
      - name: select
        in: query
        description: The number of records to select between 1 and 1000
        required: false
        schema:
          type: integer
          format: int32
      - name: skip
        in: query
        description: The numbers of records to skip in the result set
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 2
                    name:
                      type: string
                      examples:
                      - Address book 2
                    visibility:
                      type: string
                      examples:
                      - Private
                    contacts:
                      type: integer
                      default: 0
                      examples:
                      - 5
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 2
                    name: Address book 2
                    visibility: Private
                    contacts: 5
                  - id: 3
                    name: Address book 3
                    visibility: Private
                    contacts: 7
  /v2/address-books/{id}/contacts/unsubscribed-since/{date}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get unsubscribed from list since date
      deprecated: false
      description: Gets a list of contacts who have unsubscribed since a given date from a given list / address book
      operationId: get-unsubscribed-contacts-from-address-book-since-date
      tags:
      - Lists / Address books
      parameters:
      - name: id
        in: path
        description: The id of the list / address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: date
        in: path
        description: The date from which any unsubscribed contacts are returned in [ISO 8601 format](https://www.w3.org/TR/xmlschema-2/#dateTime)
        required: true
        example: ''
        schema:
          type: string
          format: date
      - name: select
        in: query
        description: The number of records to select between 1 and 1000
        required: false
        schema:
          type: integer
          format: int32
      - name: skip
        in: query
        description: The numbers of records to skip in the result set
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                Result:
                  summary: Result
                  value: '[

                    {

                    "suppressedContact": {

                    "id": 1,

                    "email": "nelson.redeker@example.com",

                    "optInType": "Unknown",

                    "emailType": "PlainText",

                    "dataFields": null,

                    "status": "Unsubscribed"

                    },

                    "dateRemoved": "2020-01-01T09:40:18.527Z",

                    "reason": "Unsubscribed"

                    },

                    {

                    "suppressedContact": {

                    "id": 25,

                    "email": "terry.mccarthy@example.com",

                    "optInType": "VerifiedDouble",

                    "emailType": "Html",

                    "dataFields": null,

                    "status": "Unsubscribed"

                    },

                    "dateRemoved": "2020-01-01T09:40:18.527Z",

                    "reason": "Unsubscribed"

                    },

                    ]'
  /v2/address-books/{id}/contacts/unsubscribe:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    post:
      summary: Unsubscribe contact from list
      deprecated: false
      description: Unsubscribes contact from a given list / address book
      operationId: unsubscribe-contact-from-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: id
        in: path
        description: The id of the list / address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  description: The email address of the contact to be unsubscribed
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  suppressedContact:
                    type: object
                    properties:
                      id:
                        type: integer
                        default: 0
                        examples:
                        - 123456
                      email:
                        type: string
                        examples:
                        - example@emailsim.io
                      optInType:
                        type: string
                        examples:
                        - Unknown
                      emailType:
                        type: string
                        examples:
                        - Html
                      dataFields: {}
                      status:
                        type: string
                        examples:
                        - Subscribed
                  dateRemoved:
                    type: string
                    examples:
                    - '2025-07-23 11:01:55.433000+00:00'
                  reason:
                    type: string
                    examples:
                    - Unsubscribed
              examples:
                Result:
                  summary: Result
                  value:
                    suppressedContact:
                      id: 123456
                      email: example@emailsim.io
                      optInType: Unknown
                      emailType: Html
                      dataFields: null
                      status: Subscribed
                    dateRemoved: '2025-07-23 11:01:55.433000+00:00'
                    reason: Unsubscribed
  /v2/address-books/{id}/contacts/resubscribe:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    post:
      summary: Resubscribe contact to list
      deprecated: false
      description: Resubscribes a previously unsubscribed contact to a given list / address book
      operationId: resubscribe-contact-to-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: id
        in: path
        description: The id of the list / address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - unsubscribedContact
              properties:
                unsubscribedContact:
                  type: object
                  description: The details of the contact to be resubscribed
                  required:
                  - email
                  properties:
                    email:
                      type: string
                      description: The email address of the contact
                    dataFields:
                      type: array
                      description: The data fields for the contact
                      items:
                        properties:
                          key:
                            type: string
                            description: The key name
                          value:
                            type: string
                            description: The value associated with the key
                        required:
                        - key
                        - value
                        type: object
                preferredLocale:
                  type: string
                  description: The language code for the language you would like the resubscribe request email to be sent to the contact in
                  enum:
                  - cs-CS
                  - da-DA
                  - de-DE
                  - el-EL
                  - en-EN
                  - es-ES
                  - es
                  - fi-FI
                  - fr-FR
                  - hu-HU
                  - it-IT
                  - nl-NL
                  - nb-NO
                  - pl-PL
                  - pt-PT
                  - ru-RU
                  - se-SE
                  - sk-SK
                  - tr-TR
                  - zh-CN
                returnUrlToUseIfChallenged:
                  type: string
                  description: The URL you would like to redirect challenged contacts to after they have completed their resubscription
            examples:
              Request Example:
                value:
                  unsubscribedContact:
                    email: john.smith@emailsim.io
                    dataFields:
                    - key: FIRSTNAME
                      value: Nelson
                    - key: LASTNAME
                      value: Redeker
                  preferredLocale: de-DE
                  returnUrlToUseIfChallenged: https://www.mywebsite.com/news
                summary: Request Example
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    type: object
                    properties:
                      id:
                        type: integer
                        default: 0
                        examples:
                        - 23
                      email:
                        type: string
                        examples:
                        - john.smith@emailsim.io
                      optInType:
                        type: string
                        examples:
                        - Unknown
                      emailType:
                        type: string
                        examples:
                        - PlainText
                      dataFields: {}
                      status:
                        type: string
                        examples:
                        - Unsubscribed
                  status:
                    type: string
                    examples:
                    - ContactChallenged
              examples:
                Result:
                  summary: Result
                  value:
                    contact:
                      id: 23
                      email: john.smith@emailsim.io
                      optInType: Unknown
                      emailType: PlainText
                      dataFields: null
                      status: Unsubscribed
                    status: ContactChallenged
  /v2/address-books/{id}/contacts/resubscribe-with-no-challenge:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    post:
      summary: Resubscribe contact to list with no challenge
      deprecated: false
      description: Resubscribes a previously unsubscribed contact to a specific list / address book without sending a challenge email
      operationId: resubscribe-contact-to-address-book-with-no-challenge
      tags:
      - Lists / Address books
      parameters:
      - name: id
        in: path
        description: The ID of the list / address book, which needs to be included within the URL
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                unsubscribedContact:
                  type: object
                  description: The email address of the unsubscribed contact, which needs to be included within the request body
                  required:
                  - email
                  properties:
                    email:
                      type: string
                      description: The email address of the contact
                    dataFields:
                      type: array
                      description: The data fields for the contact
                      items:
                        properties:
                          key:
                            type: string
                            description: The key name
                          value:
                            type: string
                            description: The value associated with the key
                        required:
                        - key
                        - value
                        type: object
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    type: object
                    properties:
                      id:
                        type: integer
                        default: 0
                        examples:
                        - 24
                      email:
                        type: string
                        examples:
                        - john.smith@emailsim.io
                      optInType:
                        type: string
                        examples:
                        - Unknown
                      emailType:
                        type: string
                        examples:
                        - PlainText
                      dataFields: {}
                      status:
                        type: string
                        examples:
                        - Subscribed
                  status:
                    type: string
                    examples:
                    - ContactAdded
              examples:
                Result:
                  summary: Result
                  value:
                    contact:
                      id: 24
                      email: john.smith@emailsim.io
                      optInType: Unknown
                      emailType: PlainText
                      dataFields: null
                      status: Subscribed
                    status: ContactAdded
  /v2/address-books/{addressBookId}/contacts/{contactId}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    delete:
      summary: Delete contact from list
      deprecated: false
      description: Deletes a contact from a given list / address book
      operationId: delete-contact-from-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: addressBookId
        in: path
        description: The id of the list / address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: contactId
        in: path
        description: The id of the contact
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      responses:
        '204':
          description: '204'
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                Result:
                  summary: Result
                  value: {}
  /v2/address-books/{addressBookId}/contacts/delete:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    post:
      summary: Delete contacts from list
      deprecated: false
      description: Deletes multiple contacts from an list / address book
      operationId: delete-contacts-from-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: addressBookId
        in: path
        description: The id of the list / address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - RAW_BODY
              properties:
                RAW_BODY:
                  type: array
                  description: The IDs of the contacts that need deleting from the address book
                  items:
                    type: integer
                    format: int32
            examples:
              Request Example:
                value:
                - 684095989
                - 1182927244
                summary: Request Example
      responses:
        '202':
          description: '202'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    examples:
                    - 13e7b388-2060-4f58-b3dc-2885badf80ee
                  status:
                    type: string
                    examples:
                    - Started
              examples:
                Result:
                  summary: Result
                  value:
                    id: 13e7b388-2060-4f58-b3dc-2885badf80ee
                    status: Started
  /v2/address-books/{addressBookId}/contacts/delete-all:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    post:
      summary: Delete all contacts from list
      deprecated: false
      description: Deletes all contacts from a given list / address book
      operationId: delete-all-contacts-from-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: addressBookId
        in: path
        description: The id of the list / address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      responses:
        '202':
          description: '202'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    examples:
                    - 13e7b388-2060-4f58-b3dc-2885badf80ee
                  status:
                    type: string
                    examples:
                    - Started
              examples:
                Result:
                  summary: Result
                  value:
                    id: 13e7b388-2060-4f58-b3dc-2885badf80ee
                    status: Started
  /v2/address-books/{addressBookId}/contacts/with-preference/{preferenceId}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get contacts opted into a preference and an address book
      deprecated: false
      description: Gets contacts who are opted into a given preference and a given address book
      operationId: get-contacts-opted-into-a-preference-and-an-address-book
      tags:
      - Lists / Address books
      parameters:
      - name: addressBookId
        in: path
        description: The ID of the address book to which contacts must belong.
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: preferenceId
        in: path
        description: The ID of the preference to which contacts must be opted in.
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: minContactID
        in: query
        description: The minimum contact ID to query on, starting from 0
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                Result:
                  summary: Result
                  value: '[

                    {

                    "id": 279,

                    "email": "joe.bloggs@emailsim.io"

                    },

                    {

                    "id": 99123,

                    "email": "joanne.bloggs@emailsim.io"

                    },

                    ]'
  /v2/address-books/{addressBookId}/contacts/with-preference/{preferenceId}/opt-ins-since/{date}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get contacts with modified preference opt-in in address book since date
      deprecated: false
      description: Gets the top 1000 contacts who have had a specific preference opt-in status modified since a given date, in a given address book
      operationId: get-contacts-with-modified-preference-opt-in-in-address-book-since-date
      tags:
      - Lists / Address books
      parameters:
      - name: addressBookId
        in: path
        description: The ID of the address book to which contacts must belong.
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: preferenceId
        in: path
        description: The ID of the preference to which contacts must be opted in.
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: date
        in: path
        description: The earliest date that returned contacts must have modified their opt-in status for the preference in [ISO 8601 format](https://www.w3.org/TR/xmlschema-2/#dateTime)
        required: true
        example: ''
        schema:
          type: string
          format: date
      - name: minContactID
        in: query
        description: The minimum contact ID to query on, starting from 0
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    contact:
                      type: object
                      properties:
                        id:
                          type: integer
                          default: 0
                          examples:
                          - 5
                        email:
                          type: string
                          examples:
                          - darryl.netherland@example.com
                        optInType:
                          type: string
                          examples:
                          - Single
                        emailType:
                          type: string
                          examples:
                          - Html
                        dataFields: {}
                        status:
                          type: string
                          examples:
                          - Subscribed
                    marketingPreferenceOptIns:
                      type: array
                      items:
                        type: object
                        properties:
                          marketingPreferenceId:
                            type: integer
                            default: 0
                            examples:
                            - 2
                          addressBookId:
                            type: integer
                            default: 0
                            examples:
                            - 421
                          isOptedIn:
                            type: boolean
                            default: true
                            examples:
                            - false
                          dateModifed:
                            type: string
                            examples:
                            - '2020-01-01 09:40:18.527000+00:00'
              examples:
                Result:
                  summary: Result
                  value:
                  - contact:
                      id: 5
                      email: darryl.netherland@example.com
                      optInType: Single
                      emailType: Html
                      dataFields: null
                      status: Subscribed
                    marketingPreferenceOptIns:
                    - marketingPreferenceId: 2
                      addressBookId: 421
                      isOptedIn: false
                      dateModifed: '2020-01-01 09:40:18.527000+00:00'
                  - contact:
                      id: 12
                      email: dora.judge@example.com
                      optInType: Unknown
                      emailType: Html
                      dataFields: null
                      status: Subscribed
                    marketingPreferenceOptIns:
                    - marketingPreferenceId: 5
                      addressBookId: 395
                      isOptedIn: true
                      dateModifed: '2020-01-01 09:40:18.527000+00:00'
  /v2/address-books/{id}/contacts/import/with-merge-option/{mergeOption}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    post:
      summary: Bulk import contacts in address book with merge option
      deprecated: true
      description: Bulk creates, or bulk updates, contacts in an address book with merge option
      operationId: bulk-import-contacts-in-address-book-with-merge-option
      tags:
      - Lists / Address books - Deprecated
      parameters:
      - name: id
        in: path
        description: The address book id
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: mergeOption
        in: path
        description: 'For Merge options: you can update all data fields by entering ''''0'''', avoid updating data fields that contain blank values by entering ''''1'''', or you can choose not to update data fields that contain values by entering ''''2'''''
        required: true
        example: ''
        schema:
          type: string
          enum:
          - '0'
          - '1'
          - '2'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - filename
              - data
              properties:
                filename:
                  type: string
                  description: The filename of the file being uploaded
                data:
                  type: string
                  description: The [base64](https://en.wikipedia.org/wiki/Base64) data for the file
      responses:
        '202':
          description: '202'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    examples:
                    - af4ac4bc-e1e7-4817-8a66-73fb59e91ce6
                  status:
                    type: string
                    examples:
                    - NotFinished
              examples:
                Result:
                  summary: Result
                  value:
                    id: af4ac4bc-e1e7-4817-8a66-73fb59e91ce6
                    status: NotFinished
      x-readme:
        code-samples:
        - language: text
          code: 'Email,Firstname,Lastname,Postcode,Customfield_1,Customfield_2

            user1@example.com,Bob,Smith,LXS123,Yes,100

            user2@example.com,Frank,Smith,LXS121,No,200

            user3@example.com,Sarah,Smith,LXS124,Yes,300'
          name: CSV Example
        samples-languages:
        - text
  /v2/address-books/{id}/contacts/modified-since/{date}:
    get:
      summary: Get modified contacts in address book since date
      deprecated: true
      description: Gets a list of contacts who were modified since a given date, in a given address book or segment
      operationId: get-modified-contacts-in-address-book-since-date
      tags:
      - Lists / Address books - Deprecated
      parameters:
      - name: id
        in: path
        description: The ID of the address book or segment
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: date
        in: path
        description: The date from which any modified contacts are returned in [ISO 8601 format](https://www.w3.org/TR/xmlschema-2/#dateTime)
        required: true
        example: ''
        schema:
          type: string
          format: date
      - name: withFullData
        in: query
        description: Can be set to 'true' to retrieve the contacts along with their full contact data fields
        required: false
        schema:
          type: boolean
          default: false
      - name: select
        in: query
        description: he select parameter requires a number between 1 and 1000 (0 is not a valid number). You may only select a maximum of 1000 results in a single request. This parameter goes within the URL.
        required: false
        schema:
          type: integer
          format: int32
      - name: skip
        in: query
        description: The skip parameter should be used in tandem with the select parameter when wanting to iterate through a whole data set. If you want to select the next 1000 records you should set the select parameter to 1000 and the skip parameter to 1000, which will return records 1001 to 2000. You should continue to do this until 0 records are returned to retrieve the whole data set.
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 5
                    email:
                      type: string
                      examples:
                      - darryl.netherland@example.com
                    optInType:
                      type: string
                      examples:
                      - Single
                    emailType:
                      type: string
                      examples:
                      - PlainText
                    dataFields: {}
                    status:
                      type: string
                      examples:
                      - Subscribed
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 5
                    email: darryl.netherland@example.com
                    optInType: Single
                    emailType: PlainText
                    dataFields: null
                    status: Subscribed
                  - id: 17
                    email: dora.judge@example.com
                    optInType: Single
                    emailType: PlainText
                    dataFields: null
                    status: Subscribed
                  - id: 21
                    email: deonna.medine@example.com
                    optInType: Single
                    emailType: PlainText
                    dataFields: null
                    status: Subscribed
          headers: {}
  /v2/address-books/{id}/contacts:
    get:
      summary: Get contacts from address book
      deprecated: true
      description: Gets a list of contacts in a given address book or segment by id
      operationId: get-contacts-from-address-book
      tags:
      - Lists / Address books - Deprecated
      parameters:
      - name: id
        in: path
        description: The ID of the address book or segment
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      - name: withFullData
        in: query
        description: Can be set to 'true' to retrieve the contacts along with their full contact data fields
        required: false
        schema:
          type: boolean
          default: false
      - name: select
        in: query
        description: he select parameter requires a number between 1 and 1000 (0 is not a valid number). You may only select a maximum of 1000 results in a single request. This parameter goes within the URL.
        required: false
        schema:
          type: integer
          format: int32
      - name: skip
        in: query
        description: The skip parameter should be used in tandem with the select parameter when wanting to iterate through a whole data set. If you want to select the next 1000 records you should set the select parameter to 1000 and the skip parameter to 1000, which will return records 1001 to 2000. You should continue to do this until 0 records are returned to retrieve the whole data set.
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - email
                  - optInType
                  - emailType
                  - status
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 5
                    email:
                      type: string
                      examples:
                      - darryl.netherland@example.com
                    optInType:
                      type: string
                      examples:
                      - Single
                    emailType:
                      type: string
                      examples:
                      - PlainText
                    dataFields: {}
                    status:
                      type: string
                      examples:
                      - Subscribed
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 5
                    email: darryl.netherland@example.com
                    optInType: Single
                    emailType: PlainText
                    dataFields: null
                    status: Subscribed
                  - id: 17
                    email: dora.judge@example.com
                    optInType: Single
                    emailType: PlainText
                    dataFields: null
                    status: Subscribed
                  - id: 21
                    email: deonna.medine@example.com
                    optInType: Single
                    emailType: PlainText
                    dataFields: null
                    status: Subscribed
          headers: {}
    post:
      summary: Add contact to address book
      deprecated: true
      description: Adds a contact to a given address book.
      operationId: add-contact-to-address-book
      tags:
      - Lists / Address books - Deprecated
      parameters:
      - name: id
        in: path
        description: The id of the address book
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: The email address of the contact
                optInType:
                  type: string
                  description: The opt-in type of the contact
                  enum:
                  - Unknown
                  - Single
                  - Double
                  - VerifiedDouble
                emailType:
                  type: string
                  description: The email type of the contact
                  enum:
                  - PlainText
                  - Html
                dataFields:
                  type: array
                  description: The data fields for the contact
                  items:
                    type: object
                    required:
                    - key
                    - value
                    properties:
                      key:
                        type: string
                        description: The key name
                      value:
                        type: string
                        description: The value associated with the key
            examples:
              Request Example:
                summary: Request Example
                value:
                  email: john.smith@example.com
                  optInType: Single
                  emailType: Html
                  dataFields:
                  - key: FIRSTNAME
                    value: John
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  email:
                    type: string
                    format: email
                    examples:
                    - john.smith@example.com
                  optInType:
                    type: string
                    examples:
                    - Single
                  emailType:
                    type: string
                    examples:
                    - Html
                  dataFields:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          examples:
                          - FIRSTNAME
                        value:
                          type: string
                          examples:
                          - John
                  status:
                    type: string
                    examples:
                    - Subscribed
              examples:
                Result:
                  summary: Result
                  value:
                    id: 1
                    email: john.smith@example.com
                    optInType: Single
                    emailType: Html
                    dataFields:
                    - key: FIRSTNAME
                      value: John
                    - key: FULLNAME
                      value: John Smith
                    - key: GENDER
                      value: Male
                    - key: LASTNAME
                      value: Smith
                    - key: LASTSUBSCRIBED
                      value: '2020-01-01 09:40:18.527000+00:00'
                    - key: POSTCODE
                      value: N5 1DP
                    status: Subscribed
          headers: {}