EmailOctopus Tag API

openapi: 3.1.0
info:
  title: EmailOctopus v2 Tag API
  description: "# Introduction\n\nThe EmailOctopus API allows you to manage resources and perform actions within the platform\
    \ programmatically. You'll need to <a href=\"https://emailoctopus.com/account/sign-up\" target=\"_blank\">create an account</a>\
    \ before using the API, if you don't already have one.\n\nThe API is designed around <a href=\"https://en.wikipedia.org/wiki/REST\"\
    \ target=\"_blank\">REST</a> principles. It has a predictable URL structure based on resources, accepts <a href=\"https://www.json.org/json-en.html\"\
    \ target=\"_blank\">JSON-encoded</a> request bodies, returns JSON-encoded responses and uses standard HTTP response codes,\
    \ authentication and verbs.\n\nThe base URL for the API is https://api.emailoctopus.com.\n\n# Authentication\nTo use the\
    \ API, you'll need to generate an API key. You can do this in your <a href=\"https://emailoctopus.com/developer/api-keys\"\
    \ target=\"_blank\">account settings</a>. If you have an API key created prior to the release of API v2 (labelled 'legacy')\
    \ you'll need to generate a new API key. New API keys are compatible with all versions of the API.\n\nThe API uses bearer\
    \ authentication to authenticate requests. Authenticate your request by including the following header:\n```\nAuthorization:\
    \ Bearer {token}\n```\n\nFor example, using curl:\n```\ncurl https://api.emailoctopus.com/lists/ -H \"Authorization: Bearer\
    \ {token}\"\n```\n\nIf you see a JSON-formatted response with your list details, that's great! That means you can connect\
    \ to the API, and your authentication token works.\n\nIf you encounter a JSON error response, refer to the `type` field\
    \ for a link to detailed documentation. For non-JSON errors, the request likely didn't reach the server. In that case,\
    \ double-check the URL and verify that your request is correctly formatted.\n\n# Rate limiting\nRequests to the API are\
    \ subject to a rate limit, which is implemented using the <a href=\"https://en.wikipedia.org/wiki/Token_bucket\" target=\"\
    _blank\">token bucket algorithm</a>. Each request consumes one token and your bucket holds up to 100 tokens. Tokens are\
    \ replenished at a rate of 10 per second. To check your remaining tokens, refer to the `X-RateLimiting-Remaining` header\
    \ in the response.\n\nThis system enables a steady request rate of up to 10 per second or a burst of up to 100 requests\
    \ in a single instance if needed.\n\nIf your account exceeds the rate limit, the request will return a [429 HTTP status\
    \ code](https://emailoctopus.com/api-documentation/v2#too-many-requests).\n\n# Pagination\nWhen you request a collection\
    \ of entities, such as contacts belonging to a list, the data will be paginated rather than returned all at once. Each\
    \ response will contain a maximum of 100 results in the `data` attribute.\n\nPagination information is included in the\
    \ response `paging` attribute. This data will contain `next` attributes, with a URL and a `starting_after` cursor. The\
    \ cursor serves as a link to the next page. You can use the cursor as a `starting_after` query string parameter to navigate\
    \ to the next page or follow the provided URL in the JSON structure.\n\nHere's an example of what the `paging` attribute\
    \ looks like:\n```\n\"paging\": {\n    \"next\": {\n        \"url\": \"https://api.emailoctopus.com/lists/{list_id}/contacts?starting_after=WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0&limit=100\"\
    ,\n        \"starting_after\": \"WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0\"\
    \n    }\n }\n```\nYou can add the cursor to your request URL by including the `starting_after` query string parameter,\
    \ like this:\n```\nhttps://api.emailoctopus.com/lists/{list_id}/contacts?starting_after=WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0\n\
    ```\n\nThe cursor should always be provided exactly as it was returned in a previous request. Avoid deconstructing the\
    \ cursor and relying on any data inside it, as the implementation of the cursor is subject to change.\n\n# Errors\nError\
    \ are returned in a standardised format following <a href=\"https://datatracker.ietf.org/doc/html/rfc7807\" target=\"\
    _blank\">RFC 7807</a>. For example:\n\n```\n{\n    \"title\": \"An error occurred.\",\n    \"detail\": \"Bad request.\"\
    ,\n    \"status\": 400,\n    \"type\": \"https://emailoctopus.com/api-documentation/v2#bad-request\"\n}\n```\n\nYou can\
    \ use the `type` value to navigate to the documentation for more details about the specific error.\n\nYou may also encounter\
    \ validation errors, which will return a 422 HTTP status code and a payload formatted according to <a href=\"https://www.rfc-editor.org/rfc/rfc9457.html\"\
    \ target=\"_blank\">RFC 9457</a>.\n```\n{\n    \"title\": \"An error occurred.\",\n    \"detail\": \"Unprocessable content.\"\
    ,\n    \"status\": 422,\n    \"errors\": [\n         {\n            \"detail\": \"This value should not be blank.\",\n\
    \            \"pointer\": \"/email_address\"\n         }\n    ],\n    \"type\": \"https://emailoctopus.com/api-documentation/v2#unprocessable-content\"\
    \n}\n```\n\nIn the following sections, you can find more information about each type of error.\n\n## access-denied\nYou\
    \ do not have permission to access the requested entity, such as trying to get the contacts in a list belonging to another\
    \ account.\n\nCheck that the API key you're using belongs to the account you're trying to access data in. You can verify\
    \ this by navigating to the account's <a href=\"https://emailoctopus.com/developer/api-keys\" target=\"_blank\">API keys</a>\
    \ and checking there's a key ending in the same four characters.\n\n## already-exists\nYou are attempting to create an\
    \ entity that already exists, such as creating a tag on a list that already contains that tag, or adding a contact to\
    \ a list that already includes that contact.\n\nYou can fix this by checking if the entity already exists before you attempt\
    \ to create it. Or you may wish to handle the error gracefully in your code and update the existing resource when a duplicate\
    \ is spotted.\n\nSome endpoints, such as the [create or update contact](#tag/Contact/operation/api_lists_list_idcontacts_put)\
    \ endpoint, support an *upsert* operation. An upsert allows you to either update the entity if it exists or create a new\
    \ one if it doesn't. Consider using this feature where applicable.\n\n## bad-request\nThe request body is not in the format\
    \ expected. Check that the request body is valid JSON.\n\n## conflict\nThis request conflicts with the system state. <a\
    \ href=\"https://help.emailoctopus.com/category/20-getting-in-touch\" target=\"_blank\">Get in touch</a> if you require\
    \ further assistance.\n\n## internal-error\nThis error is returned when the API encounters an unexpected condition or\
    \ an internal issue on the server. If you receive this error, it is probably not an issue with your request.\n\nIn some\
    \ cases, retrying the request after some time may resolve the issue. We'll always be notified of the error via our internal\
    \ tracking tools, but if the problem persists, <a href=\"https://help.emailoctopus.com/category/20-getting-in-touch\"\
    \ target=\"_blank\">get in touch</a> with details about the error and we'll investigate.\n\n## not-found\nThe resource\
    \ you're trying to access or modify could not be found. This error is typically caused by using an invalid or incorrect\
    \ identifier, such as a list ID or contact ID that doesn't exist in your account.\n\nDouble-check the resource identifiers\
    \ you're using in your request, and ensure they match the actual resources in your EmailOctopus account.\n\n## out-of-limits\n\
    Executing this operation would cause you to exceed your plan limits. See our <a href=\"https://emailoctopus.com/pricing#comparison\"\
    \ target=\"_blank\">pricing comparison</a> for further details on these limits.\n\n## unauthorized\nThe API key provided\
    \ in the request is either invalid or missing. Ensure that you're using the correct API key and that it is included in\
    \ the request header as shown in the [authentication section](/api-documentation/v2#section/Authentication).\n\n## unprocessable-content\n\
    The JSON payload in your request body doesn't meet the required criteria. Check the errors attribute for details on the\
    \ specific issues. It will include a pointer to the problematic attribute and an error description.\n\n## unsupported-media-type\n\
    When making requests that require a JSON payload in the body, you must specify a `Content-Type` of `application/json`.\n\
    \n## too-many-requests\nYour account has exceeded the rate limit. You can use the `X-RateLimit-Retry-After` header to\
    \ determine when to make another request. See the [rate limiting section](/api-documentation/v2#section/Rate-limiting)\
    \ section for further details.\n\n## method-not-allowed\nThe HTTP method used in your request is not supported for the\
    \ endpoint you are trying to access. For example, attempting to use a POST method on an endpoint that only supports GET.\n\
    \nCheck the API documentation for the correct methods allowed for each endpoint. Ensure your request uses one of the supported\
    \ methods (e.g., GET, POST, PUT, DELETE) for the specific operation you want to perform.\n"
  version: 2.0.0
servers:
- url: https://api.emailoctopus.com
  description: ''
security:
- api_key: []
tags:
- name: Tag
  description: 'Tags are list-specific labels that you can assign to contacts to categorise or segment them. Tags allow you
    to create personalised campaigns or trigger automations based on specific attributes or behaviours.

    '
paths:
  /lists/{list_id}/tags:
    get:
      operationId: api_lists_list_idtags_get
      tags:
      - Tag
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List.tags.collection-get'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#bad-request
                    default: https://emailoctopus.com/api-documentation/v2#bad-request
                    example: https://emailoctopus.com/api-documentation/v2#bad-request
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Bad request.
                  status:
                    type: string
                    description: Response status.
                    default: 400
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                      - detail
                      properties:
                        pointer:
                          type: string
                          description: A JSON Pointer [RFC6901] to the value in the request document that caused the error.
                          default: name
                        parameter:
                          type: string
                          description: Name of the url parameter containing the error.
                          default: list_id
                        detail:
                          type: string
                          description: Error description.
                          default: This value should be between 1 and 100.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#unauthorized
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Invalid key.
                  status:
                    type: string
                    description: Response status.
                    default: 401
        '403':
          description: Access denied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#access-denied
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Access denied.
                  status:
                    type: string
                    description: Response status.
                    default: 403
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#not-found
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Resource not found.
                  status:
                    type: string
                    description: Response status.
                    default: 404
      summary: Get all tags
      description: ''
      parameters:
      - name: list_id
        in: path
        description: The ID of the list.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: 00000000-0000-0000-0000-000000000000
      - name: limit
        in: query
        description: Max number of results per page.
        required: false
        deprecated: false
        schema:
          type: integer
          default: '100'
        style: form
        explode: true
        example: '100'
      - name: starting_after
        in: query
        description: Cursor that points to the end of the page.
        required: false
        deprecated: false
        schema:
          type: string
        style: form
        explode: true
        example: WyIyMDI0LTEyLTEwVDEzOjIxOjQ2KzAwOjAwIiwxXQ
    post:
      operationId: api_lists_list_idtags_post
      tags:
      - Tag
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTag'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#bad-request
                    default: https://emailoctopus.com/api-documentation/v2#bad-request
                    example: https://emailoctopus.com/api-documentation/v2#bad-request
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Bad request.
                  status:
                    type: string
                    description: Response status.
                    default: 400
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                      - detail
                      properties:
                        pointer:
                          type: string
                          description: A JSON Pointer [RFC6901] to the value in the request document that caused the error.
                          default: name
                        parameter:
                          type: string
                          description: Name of the url parameter containing the error.
                          default: list_id
                        detail:
                          type: string
                          description: Error description.
                          default: This value should be between 1 and 100.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#unauthorized
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Invalid key.
                  status:
                    type: string
                    description: Response status.
                    default: 401
        '403':
          description: Access denied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#access-denied
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Access denied.
                  status:
                    type: string
                    description: Response status.
                    default: 403
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#not-found
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Resource not found.
                  status:
                    type: string
                    description: Response status.
                    default: 404
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#conflict
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Resource already exists.
                  status:
                    type: string
                    description: Response status.
                    default: 409
        '422':
          description: Unprocessable content.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#unprocessable-content
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Unprocessable content.
                  status:
                    type: string
                    description: Response status.
                    default: 422
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                      - detail
                      properties:
                        pointer:
                          type: string
                          description: A JSON Pointer [RFC6901] to the value in the request document that caused the error.
                          default: name
                        parameter:
                          type: string
                          description: Name of the url parameter containing the error.
                          default: list_id
                        detail:
                          type: string
                          description: Error description.
                          default: This value should be between 1 and 100.
      summary: Create tag
      description: ''
      parameters:
      - name: list_id
        in: path
        description: The ID of the list.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: 00000000-0000-0000-0000-000000000000
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListTag'
        required: false
  /lists/{list_id}/tags/{tag}:
    put:
      operationId: api_lists_list_idtags_tag_put
      tags:
      - Tag
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTag'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#bad-request
                    default: https://emailoctopus.com/api-documentation/v2#bad-request
                    example: https://emailoctopus.com/api-documentation/v2#bad-request
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Bad request.
                  status:
                    type: string
                    description: Response status.
                    default: 400
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                      - detail
                      properties:
                        pointer:
                          type: string
                          description: A JSON Pointer [RFC6901] to the value in the request document that caused the error.
                          default: name
                        parameter:
                          type: string
                          description: Name of the url parameter containing the error.
                          default: list_id
                        detail:
                          type: string
                          description: Error description.
                          default: This value should be between 1 and 100.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#unauthorized
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Invalid key.
                  status:
                    type: string
                    description: Response status.
                    default: 401
        '403':
          description: Access denied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#access-denied
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Access denied.
                  status:
                    type: string
                    description: Response status.
                    default: 403
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#not-found
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Resource not found.
                  status:
                    type: string
                    description: Response status.
                    default: 404
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#conflict
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Resource already exists.
                  status:
                    type: string
                    description: Response status.
                    default: 409
        '422':
          description: Unprocessable content.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#unprocessable-content
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Unprocessable content.
                  status:
                    type: string
                    description: Response status.
                    default: 422
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                      - detail
                      properties:
                        pointer:
                          type: string
                          description: A JSON Pointer [RFC6901] to the value in the request document that caused the error.
                          default: name
                        parameter:
                          type: string
                          description: Name of the url parameter containing the error.
                          default: list_id
                        detail:
                          type: string
                          description: Error description.
                          default: This value should be between 1 and 100.
      summary: Update tag
      description: ''
      parameters:
      - name: list_id
        in: path
        description: The ID of the list.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: 00000000-0000-0000-0000-000000000000
      - name: tag
        in: path
        description: A unique identifier for a field.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: Hometown
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListTag'
        required: false
    delete:
      operationId: api_lists_list_idtags_tag_delete
      tags:
      - Tag
      responses:
        '204':
          description: No content.
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: Error type.
                    enum:
                    - https://emailoctopus.com/api-documentation/v2#bad-request
                    default: https://emailoctopus.com/api-documentation/v2#bad-request
                    example: https://emailoctopus.com/api-documentation/v2#bad-request
                  title:
                    type: string
                    description: General error title.
                    default: An error occurred.
                  detail:
                    type: string
                    description: Error description.
                    default: Bad request.
                  status:
                    type: string
                    description: Response status.
                    default: 

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