EmailOctopus v2 API (2.0.0)

The EmailOctopus API allows you to manage resources and perform actions within the platform programmatically. You'll need to create an account before using the API, if you don't already have one.

The API is designed around REST principles. It has a predictable URL structure based on resources, accepts JSON-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication and verbs.

The base URL for the API is https://api.emailoctopus.com.

To use the API, you'll need to generate an API key. You can do this in your account settings. 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.

The API uses bearer authentication to authenticate requests. Authenticate your request by including the following header:

Authorization: Bearer {token}

For example, using curl:

curl https://api.emailoctopus.com/lists/ -H "Authorization: Bearer {token}"

If 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.

If 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.

Requests to the API are subject to a rate limit, which is implemented using the token bucket algorithm. 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.

This 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.

If your account exceeds the rate limit, the request will return a 429 HTTP status code.

When 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.

Pagination 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.

Here's an example of what the paging attribute looks like:

"paging": {
    "next": {
        "url": "https://api.emailoctopus.com/lists/{list_id}/contacts?starting_after=WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0&limit=100",
        "starting_after": "WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0"
    }
 }

You can add the cursor to your request URL by including the starting_after query string parameter, like this:

https://api.emailoctopus.com/lists/{list_id}/contacts?starting_after=WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0

The 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.

Error are returned in a standardised format following RFC 7807. For example:

{
    "title": "An error occurred.",
    "detail": "Bad request.",
    "status": 400,
    "type": "https://emailoctopus.com/api-documentation/v2#bad-request"
}

You can use the type value to navigate to the documentation for more details about the specific error.

You may also encounter validation errors, which will return a 422 HTTP status code and a payload formatted according to RFC 9457.

{
    "title": "An error occurred.",
    "detail": "Unprocessable content.",
    "status": 422,
    "errors": [
         {
            "detail": "This value should not be blank.",
            "pointer": "/email_address"
         }
    ],
    "type": "https://emailoctopus.com/api-documentation/v2#unprocessable-content"
}

In the following sections, you can find more information about each type of error.

You do not have permission to access the requested entity, such as trying to get the contacts in a list belonging to another account.

Check 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 API keys and checking there's a key ending in the same four characters.

You 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.

You 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.

Some endpoints, such as the create or update contact 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.

The request body is not in the format expected. Check that the request body is valid JSON.

This request conflicts with the system state. Get in touch if you require further assistance.

This 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.

In 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, get in touch with details about the error and we'll investigate.

The 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.

Double-check the resource identifiers you're using in your request, and ensure they match the actual resources in your EmailOctopus account.

Executing this operation would cause you to exceed your plan limits. See our pricing comparison for further details on these limits.

The 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.

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.

When making requests that require a JSON payload in the body, you must specify a Content-Type of application/json.

Your 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 section for further details.

The 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.

Check 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.

An automation is a sequence of automated steps triggered by an event, such as when a contact subscribes to a list or is tagged. Automations allow you to automatically send emails, update fields, apply tags and more.

A campaign is generally used to send a one-off, timely email to some or all of your subscribers. For example you may use a campaign to send the latest edition of your weekly newsletter, or to announce a new feature in your product.

A contact represents an individual person within a list. For instance someone who has subscribed to your weekly newsletter. Contacts contain essential information such as their email address, name and any additional data you have collected. Contacts can also have tags, participate in automations and receive campaigns.

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.

A list is a collection of contacts. Every one of your contacts will exist inside a list. The majority of our users only require one list, but multiple lists can be created and configured with different fields and tags in order to organise distinct groups of contacts.

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.