openapi: 3.1.0
info:
title: EmailOctopus v2 Field 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: Field
description: 'Fields are custom data points associated with contacts within a specific list.
You can create additional fields to capture specific information about your contacts, such as birthday, location, age
or dietary preferences. These fields can be useful for sending more personalised and targeted emails.
'
paths:
/lists/{list_id}/fields:
post:
operationId: api_lists_list_idfields_post
tags:
- Field
responses:
'201':
description: Successful response
content:
application/json:
schema:
oneOf:
- title: Text, number or date field
description: A field that accepts a single value.
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
fallback:
type:
- string
- null
description: A default value for the field, used in campaigns when there is no other value available.
example: Unknown
required:
- label
- tag
- type
- title: Choice field
description: A field that accepts a single value from a list of choices.
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: choice_single
enum:
- choice_single
- choice_multiple
choices:
type: array
description: An array of choices for the field.
items:
type: string
example:
- One
- Two
fallback:
type:
- string
- null
description: A default value for the field, used in campaigns when there is no other value available.
example: Unknown
required:
- label
- tag
- type
- choices
'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
example: https://emailoctopus.com/api-documentation/v2#unprocessable-content
title:
type: string
description: 'General error title: `An error occurred.`'
example: An error occurred.
detail:
type: string
description: 'Error description: `Unprocessable content.`'
example: Unprocessable content.
status:
type: string
description: 'Response status: `422`'
example: 422
errors:
type: array
description: Validation errors
items:
type: object
properties:
detail:
type: string
description: Error description.
pointer:
type: string
description: A JSON Pointer <a href="https://datatracker.ietf.org/doc/html/rfc7807" target="_blank">[RFC
7807]</a> to the value in the request document that caused the error.
example:
detail: This value must be string type, int provided.
pointer: /tag
summary: Create field
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:
oneOf:
- title: Text, number or date field
description: A field that accepts a single value.
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
fallback:
type:
- string
- null
description: A default value for the field, used in campaigns when there is no other value available.
example: Unknown
required:
- label
- tag
- type
- title: Choice field
description: A field that accepts a single value from a list of choices.
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: choice_single
enum:
- choice_single
- choice_multiple
choices:
type: array
description: An array of choices for the field.
items:
type: string
example:
- One
- Two
fallback:
type:
- string
- null
description: A default value for the field, used in campaigns when there is no other value available.
example: Unknown
required:
- label
- tag
- type
- choices
required: true
/lists/{list_id}/fields/{tag}:
put:
operationId: api_lists_list_idfields_tag_put
tags:
- Field
responses:
'200':
description: Successful response
content:
application/json:
schema:
oneOf:
- title: Text, number or date field
description: A field that accepts a single value.
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
fallback:
type:
- string
- null
description: A default value for the field, used in campaigns when there is no other value available.
example: Unknown
required:
- label
- tag
- type
- title: Choice field
description: A field that accepts a single value from a list of choices.
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: choice_single
enum:
- choice_single
- choice_multiple
choices:
type: array
description: An array of choices for the field.
items:
type: string
example:
- One
- Two
fallback:
type:
- string
- null
description: A default value for the field, used in campaigns when there is no other value available.
example: Unknown
required:
- label
- tag
- type
- choices
'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
example: https://emailoctopus.com/api-documentation/v2#unprocessable-content
title:
type: string
description: 'General error title: `An error occurred.`'
example: An error occurred.
detail:
type: string
description: 'Error description: `Unprocessable content.`'
example: Unprocessable content.
status:
type: string
description: 'Response status: `422`'
example: 422
errors:
type: array
description: Validation errors
items:
type: object
properties:
detail:
type: string
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emailoctopus/refs/heads/main/openapi/emailoctopus-field-api-openapi.yml