EmailOctopus Lists API

openapi: 3.0.1
info:
  title: EmailOctopus v2 API
  description: >-
    The EmailOctopus v2 REST API lets developers manage subscriber lists,
    contacts, custom fields, tags, campaigns, automations, and campaign
    reports. All requests are made over HTTPS to https://api.emailoctopus.com
    and authenticated with a Bearer API key in the Authorization header.
  termsOfService: https://emailoctopus.com/terms
  contact:
    name: EmailOctopus Support
    url: https://help.emailoctopus.com
  version: '2.0'
servers:
  - url: https://api.emailoctopus.com
security:
  - api_key: []
tags:
  - name: List
  - name: Contact
  - name: Field
  - name: Tag
  - name: Campaign
  - name: Automation
paths:
  /lists:
    get:
      operationId: getAllLists
      tags:
        - List
      summary: Get all lists
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A paged collection of lists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCollection'
    post:
      operationId: createList
      tags:
        - List
      summary: Create list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: The name of the list.
                  example: New clients list
      responses:
        '200':
          description: The created list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
  /lists/{list_id}:
    parameters:
      - $ref: '#/components/parameters/ListId'
    get:
      operationId: getList
      tags:
        - List
      summary: Get list
      responses:
        '200':
          description: The requested list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
    put:
      operationId: updateList
      tags:
        - List
      summary: Update list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: The name of the list.
                  example: New clients list
      responses:
        '200':
          description: The updated list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
    delete:
      operationId: deleteList
      tags:
        - List
      summary: Delete a list
      responses:
        '204':
          description: The list was deleted.
  /lists/{list_id}/contacts:
    parameters:
      - $ref: '#/components/parameters/ListId'
    get:
      operationId: getContacts
      tags:
        - Contact
      summary: Get contacts
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A paged collection of contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactCollection'
    post:
      operationId: createContact
      tags:
        - Contact
      summary: Create contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactWrite'
      responses:
        '200':
          description: The created contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
    put:
      operationId: createOrUpdateContact
      tags:
        - Contact
      summary: Create or update contact
      description: >-
        Creates a contact, or updates it if a contact with the supplied email
        address already exists on the list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactWrite'
      responses:
        '200':
          description: The created or updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
  /lists/{list_id}/contacts/batch:
    parameters:
      - $ref: '#/components/parameters/ListId'
    put:
      operationId: updateMultipleContacts
      tags:
        - Contact
      summary: Update multiple list contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contacts
              properties:
                contacts:
                  type: array
                  description: The contacts to create or update.
                  items:
                    $ref: '#/components/schemas/ContactWrite'
      responses:
        '200':
          description: The result of each contact operation in the batch.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        email_address:
                          type: string
                          example: otto@example.com
                        status:
                          type: string
                          example: success
  /lists/{list_id}/contacts/{contact_id}:
    parameters:
      - $ref: '#/components/parameters/ListId'
      - $ref: '#/components/parameters/ContactId'
    get:
      operationId: getContact
      tags:
        - Contact
      summary: Get contact
      responses:
        '200':
          description: The requested contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
    put:
      operationId: updateContact
      tags:
        - Contact
      summary: Update contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactWrite'
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
    delete:
      operationId: deleteContact
      tags:
        - Contact
      summary: Delete contact
      responses:
        '204':
          description: The contact was deleted.
  /lists/{list_id}/fields:
    parameters:
      - $ref: '#/components/parameters/ListId'
    post:
      operationId: createField
      tags:
        - Field
      summary: Create field
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Field'
      responses:
        '200':
          description: The created field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
  /lists/{list_id}/fields/{tag}:
    parameters:
      - $ref: '#/components/parameters/ListId'
      - $ref: '#/components/parameters/Tag'
    put:
      operationId: updateField
      tags:
        - Field
      summary: Update field
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Field'
      responses:
        '200':
          description: The updated field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
    delete:
      operationId: deleteField
      tags:
        - Field
      summary: Delete field
      responses:
        '204':
          description: The field was deleted.
  /lists/{list_id}/tags:
    parameters:
      - $ref: '#/components/parameters/ListId'
    get:
      operationId: getAllTags
      tags:
        - Tag
      summary: Get all tags
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A paged collection of tags.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagCollection'
    post:
      operationId: createTag
      tags:
        - Tag
      summary: Create tag
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tag'
      responses:
        '200':
          description: The created tag.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
  /lists/{list_id}/tags/{tag}:
    parameters:
      - $ref: '#/components/parameters/ListId'
      - $ref: '#/components/parameters/Tag'
    put:
      operationId: updateTag
      tags:
        - Tag
      summary: Update tag
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tag'
      responses:
        '200':
          description: The updated tag.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
    delete:
      operationId: deleteTag
      tags:
        - Tag
      summary: Delete tag
      responses:
        '204':
          description: The tag was deleted.
  /campaigns:
    get:
      operationId: getAllCampaigns
      tags:
        - Campaign
      summary: Get all campaigns
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A paged collection of campaigns.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignCollection'
  /campaigns/{campaign_id}:
    parameters:
      - $ref: '#/components/parameters/CampaignId'
    get:
      operationId: getCampaign
      tags:
        - Campaign
      summary: Get campaign
      responses:
        '200':
          description: The requested campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
  /campaigns/{campaign_id}/reports/summary:
    parameters:
      - $ref: '#/components/parameters/CampaignId'
    get:
      operationId: getCampaignSummaryReport
      tags:
        - Campaign
      summary: Campaign summary report
      responses:
        '200':
          description: A summary report of the campaign's performance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignSummaryReport'
  /campaigns/{campaign_id}/reports/links:
    parameters:
      - $ref: '#/components/parameters/CampaignId'
    get:
      operationId: getCampaignLinksReport
      tags:
        - Campaign
      summary: Campaign links report
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A report of click activity per link in the campaign.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          example: https://emailoctopus.com
                        clicked:
                          type: object
                          properties:
                            total:
                              type: integer
                              example: 110
                            unique:
                              type: integer
                              example: 85
  /campaigns/{campaign_id}/reports:
    parameters:
      - $ref: '#/components/parameters/CampaignId'
    get:
      operationId: getCampaignContactReports
      tags:
        - Campaign
      summary: Campaign contact reports
      description: >-
        Per-contact activity for a campaign. The report type (sent, opened,
        clicked, bounced, complained, unsubscribed, etc.) is selected via the
        type query parameter.
      parameters:
        - name: type
          in: query
          required: true
          description: The type of contact report to return.
          schema:
            type: string
            enum:
              - sent
              - opened
              - clicked
              - bounced
              - complained
              - unsubscribed
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A paged collection of contacts for the requested report type.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  paging:
                    $ref: '#/components/schemas/Paging'
  /automations/{automation_id}/queue:
    parameters:
      - name: automation_id
        in: path
        required: true
        description: The ID of the automation.
        schema:
          type: string
          example: 00000000-0000-0000-0000-000000000000
    post:
      operationId: startAutomation
      tags:
        - Automation
      summary: Start an automation for a contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - list_id
                - contact_id
              properties:
                list_id:
                  type: string
                  description: The ID of the list the contact belongs to.
                  example: 00000000-0000-0000-0000-000000000000
                contact_id:
                  type: string
                  description: The ID of the contact to enter into the automation.
                  example: 00000000-0000-0000-0000-000000000000
      responses:
        '202':
          description: The contact was queued into the automation.
components:
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      description: >-
        Bearer API key in the Authorization header. Create a key at
        https://api.emailoctopus.com/developer/api-keys/create
  parameters:
    ListId:
      name: list_id
      in: path
      required: true
      description: The ID of the list.
      schema:
        type: string
        example: 00000000-0000-0000-0000-000000000000
    ContactId:
      name: contact_id
      in: path
      required: true
      description: The ID of the contact (a UUID or the MD5 hash of the lowercased email).
      schema:
        type: string
        example: 00000000-0000-0000-0000-000000000000
    CampaignId:
      name: campaign_id
      in: path
      required: true
      description: The ID of the campaign.
      schema:
        type: string
        example: 00000000-0000-0000-0000-000000000000
    Tag:
      name: tag
      in: path
      required: true
      description: The tag identifier.
      schema:
        type: string
        example: my tag
    Limit:
      name: limit
      in: query
      required: false
      description: The maximum number of records to return per page.
      schema:
        type: integer
        default: 100
        maximum: 1000
    StartingAfter:
      name: starting_after
      in: query
      required: false
      description: A cursor for pagination; the ID of the last record on the previous page.
      schema:
        type: string
  schemas:
    List:
      type: object
      properties:
        id:
          type: string
          description: The ID of the list.
          example: 00000000-0000-0000-0000-000000000000
        name:
          type: string
          maxLength: 255
          description: The name of the list.
          example: New clients list
        double_opt_in:
          type: boolean
          description: If double opt-in has been enabled on the list.
          example: false
        fields:
          type: array
          description: The custom fields available on the list.
          items:
            $ref: '#/components/schemas/Field'
        counts:
          type: object
          description: Contact counts by status.
          properties:
            pending:
              type: integer
              example: 1
            subscribed:
              type: integer
              example: 10
            unsubscribed:
              type: integer
              example: 2
        created_at:
          type: string
          format: date-time
          description: When the list was created, in ISO 8601 format.
          example: '2024-10-07T12:00:00+00:00'
    ListCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/List'
        paging:
          $ref: '#/components/schemas/Paging'
    Field:
      type: object
      properties:
        label:
          type: string
          description: A human readable label for the field.
          example: What is your hometown?
        tag:
          type: string
          description: The ID used to reference the field in your emails.
          example: Hometown
        type:
          type: string
          description: The type of the field.
          example: text
          enum:
            - text
            - number
            - date
            - choice_single
            - choice_multiple
        choices:
          type: array
          description: An array of choices for choice fields.
          items:
            type: string
          example:
            - One
            - Two
        fallback:
          type: string
          nullable: true
          description: A default value used in campaigns when no other value is available.
          example: Unknown
    Tag:
      type: object
      properties:
        tag:
          type: string
          description: The name of the tag.
          example: my tag
    TagCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        paging:
          $ref: '#/components/schemas/Paging'
    Contact:
      type: object
      description: Details of a contact of a list.
      properties:
        id:
          type: string
          description: The ID of the contact.
          example: 00000000-0000-0000-0000-000000000000
        email_address:
          type: string
          description: The email address of the contact.
          example: otto@example.com
        fields:
          type: object
          description: Key/value pairs of field values, keyed by field tag.
          additionalProperties: true
          example:
            referral: Otto
            birthday: '2015-12-01'
        status:
          type: string
          description: The subscription status of the contact.
          example: subscribed
          enum:
            - subscribed
            - unsubscribed
            - pending
        tags:
          type: array
          description: Tags associated with the contact.
          items:
            type: string
          example:
            - vip
        created_at:
          type: string
          format: date-time
          example: '2024-10-07T12:00:00+00:00'
        last_updated_at:
          type: string
          format: date-time
          example: '2024-10-07T12:00:00+00:00'
    ContactWrite:
      type: object
      required:
        - email_address
      properties:
        email_address:
          type: string
          description: The email address of the contact.
          example: otto@example.com
        fields:
          type: object
          description: >-
            Key/value pairs of field values, keyed by field tag. Pass null to
            remove a field from the contact.
          additionalProperties: true
          example:
            referral: Otto
            birthday: '2015-12-01'
        tags:
          type: object
          description: >-
            Tags to add or remove, keyed by tag name with a boolean value
            (true to add, false to remove).
          additionalProperties:
            type: boolean
          example:
            vip: true
        status:
          type: string
          description: The subscription status to set for the contact.
          example: subscribed
          enum:
            - subscribed
            - unsubscribed
            - pending
    ContactCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        paging:
          $ref: '#/components/schemas/Paging'
    Campaign:
      type: object
      description: Details of a campaign.
      properties:
        id:
          type: string
          description: The ID of the campaign.
          example: 00000000-0000-0000-0000-000000000000
        status:
          type: string
          description: The status of the campaign.
          example: draft
          enum:
            - draft
            - sending
            - sent
            - error
        name:
          type: string
          maxLength: 255
          description: The name of the campaign.
          example: New clients campaign
        subject:
          type: string
          maxLength: 255
          description: The subject of the campaign.
          example: Hello
        to:
          type: array
          description: The IDs of the lists the campaign was sent to.
          items:
            type: string
          example:
            - 00000000-0000-0000-0000-000000000000
        from:
          type: object
          description: The sender of the campaign.
          properties:
            name:
              type: string
              example: Otto Octopus
            email_address:
              type: string
              example: otto@example.com
        content:
          type: object
          description: The content of the campaign.
          properties:
            html:
              type: string
              example: <p>Hello</p>
            plain_text:
              type: string
              example: Hello
        created_at:
          type: string
          format: date-time
          example: '2024-10-07T12:00:00+00:00'
        sent_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-10-08T12:00:00+00:00'
    CampaignCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Campaign'
        paging:
          $ref: '#/components/schemas/Paging'
    CampaignSummaryReport:
      type: object
      description: A summary of a campaign's performance.
      properties:
        id:
          type: string
          example: 00000000-0000-0000-0000-000000000000
        sent:
          type: integer
          description: The number of contacts that were sent to.
          example: 200
        bounced:
          type: object
          properties:
            hard:
              type: integer
              example: 10
            soft:
              type: integer
              example: 5
        opened:
          type: object
          properties:
            total:
              type: integer
              example: 110
            unique:
              type: integer
              example: 85
        clicked:
          type: object
          properties:
            total:
              type: integer
              example: 110
            unique:
              type: integer
              example: 85
        complained:
          type: integer
          example: 50
        unsubscribed:
          type: integer
          example: 20
    Paging:
      type: object
      description: Cursor pagination metadata.
      properties:
        next:
          type: string
          nullable: true
          description: The path to the next page of results, or null if none.
          example: /lists?limit=100&starting_after=00000000-0000-0000-0000-000000000000
        previous:
          type: string
          nullable: true
          description: The path to the previous page of results, or null if none.
          example: null