EmailOctopus API v2

https://emailoctopus.com/api-documentation/v2
Admin
The EmailOctopus v2 API allows developers to manage subscribers, campaigns, and lists for email...
Tokens:19,299
Snippets:105
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get All Lists Response Example

Source: https://emailoctopus.com/api-documentation/v2

This is an example of a successful JSON response when retrieving all lists. It includes list details, custom fields, tags, and pagination information.

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "New clients list",
      "double_opt_in": false,
      "fields": [
        {
          "label": "What is your hometown?",
          "tag": "Hometown",
          "type": "text",
          "fallback": "Unknown"
}
],
      "tags": [
        "welcome"
],
      "counts": [
        {
          "pending": 0,
          "subscribed": 0,
          "unsubscribed": 0
}
],
      "created_at": "2015-12-01T12:59:37+00:00",
      "last_updated_at": "2015-12-01T12:59:37+00:00"
}
],
  "paging": {
    "next": {
      "url": "https://api.emailoctopus.com/lists?limit=10&starting_after=WyJiOWYyNjA5OC1kZjcxLTExZWUtOTQ4Zi00Yjc0NTg4MjVjYzAiXQ",
      "starting_after": "WyJiOWYyNjA5OC1kZjcxLTExZWUtOTQ4Zi00Yjc0NTg4MjVjYzAiXQ"
}
}

}
```

--------------------------------

### API Authentication Example

Source: https://emailoctopus.com/api-documentation/v2

This example demonstrates how to authenticate your API requests using a bearer token. Replace {token} with your actual API key.

```APIDOC
## API Authentication

To use the API, you'll need to generate an API key. You can do this in your account settings.

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

```
Authorization: Bearer {token}
```

### Example Request

```bash
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.
```

--------------------------------

### Start an automation for a contact

Source: https://emailoctopus.com/api-documentation/v2

Starts a specified automation for a given contact. The automation must be configured with the 'Started via API' trigger type. Contacts can only trigger an automation once unless explicitly allowed to repeat.

```APIDOC
## POST /automations/{automation_id}/queue

### Description
Starts a specified automation for a given contact. The automation must be configured with the 'Started via API' trigger type. Contacts can only trigger an automation once unless explicitly allowed to repeat.

### Method
POST

### Endpoint
https://api.emailoctopus.com/automations/{automation_id}/queue

### Parameters
#### Path Parameters
- **automation_id** (string) - Required - The ID of the automation.

#### Request Body
- **contact_id** (string) - Required - The ID of the contact, or an MD5 hash of the lowercase version of the contact's email address.

### Request Example
```json
{
  "contact_id": "631251b876fece73bc9dd647fe596d5f"
}
```

### Response
#### Success Response (204)
No content.

#### Error Responses
- **400** Bad request.
- **401** Unauthorized
- **403** Access denied.
- **404** Resource not found.
- **409** Conflict.
- **422** Unprocessable content.

#### Response Example (400)
```json
{
  "type": "https://emailoctopus.com/api-documentation/v2#bad-request",
  "title": "An error occurred.",
  "detail": "Bad request.",
  "status": 400,
  "errors": [
    {
      "pointer": "name",
      "parameter": "list_id",
      "detail": "This value should be between 1 and 100."
    }
  ]
}
```
```

--------------------------------

### Start Automation for Contact

Source: https://emailoctopus.com/api-documentation/v2

Initiates an automation for a specific contact. The automation must be configured to start via API. A contact can only trigger an automation once unless repeats are enabled.

```json
{
  "contact_id": "631251b876fece73bc9dd647fe596d5f"
}
```

--------------------------------

### Get all campaigns

Source: https://emailoctopus.com/api-documentation/v2

Retrieves a list of all campaigns. Supports filtering by limit and pagination using starting_after.

```APIDOC
## Get all campaigns

### Description
Retrieves a list of all campaigns. Supports filtering by limit and pagination using starting_after.

### Method
GET

### Endpoint
https://api.emailoctopus.com/campaigns

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max number of results per page. Default: "100"
- **starting_after** (string) - Optional - Cursor that points to the end of the page.

### Request Example
```curl
curl --request GET \
  --url https://api.emailoctopus.com/campaigns \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

### Response
#### Success Response (200)
- **data** (array) - List of campaign objects.
- **paging** (object) - Pagination information.

#### Response Example
```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status": "draft",
      "name": "New clients campaign",
      "subject": "Hello",
      "to": [
        [
          "00000000-0000-0000-0000-000000000000"
        ]
      ],
      "from": {
        "name": "Otto Octopus",
        "email_address": "otto@example.com"
      },
      "content": {
        "html": "<html>Foo Bar</html>"
      },
      "created_at": "2015-12-01T12:59:37+00:00",
      "sent_at": "2015-12-01T12:59:37+00:00"
    }
  ],
  "paging": {
    "next": {
      "url": "https://api.emailoctopus.com/lists?limit=10&starting_after=WyJiOWYyNjA5OC1kZjcxLTExZWUtOTQ4Zi00Yjc0NTg4MjVjYzAiXQ",
      "starting_after": "WyJiOWYyNjA5OC1kZjcxLTExZWUtOTQ4Zi00Yjc0NTg4MjVjYzAiXQ"
    }
  }
}
```
```

--------------------------------

### Campaign Response Sample (JSON)

Source: https://emailoctopus.com/api-documentation/v2

This is an example of a successful JSON response when retrieving campaign data. It includes details about the campaign and pagination information.

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status": "draft",
      "name": "New clients campaign",
      "subject": "Hello",
      "to": [
        [
          "00000000-0000-0000-0000-000000000000"
]
],
      "from": {
        "name": "Otto Octopus",
        "email_address": "otto@example.com"
},
      "content": {
        "html": "<html>Foo Bar</html>"
},
      "created_at": "2015-12-01T12:59:37+00:00",
      "sent_at": "2015-12-01T12:59:37+00:00"
}
],
  "paging": {
    "next": {
      "url": "https://api.emailoctopus.com/lists?limit=10&starting_after=WyJiOWYyNjA5OC1kZjcxLTExZWUtOTQ4Zi00Yjc0NTg4MjVjYzAiXQ",
      "starting_after": "WyJiOWYyNjA5OC1kZjcxLTExZWUtOTQ4Zi00Yjc0NTg4MjVjYzAiXQ"
}
}

}
```

--------------------------------

### Get All Campaigns (Shell + Curl)

Source: https://emailoctopus.com/api-documentation/v2

Use this snippet to retrieve a list of all campaigns. Ensure you replace 'REPLACE_BEARER_TOKEN' with your actual API key.

```shell
curl --request GET \
  --url https://api.emailoctopus.com/campaigns \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Example API Request with Curl

Source: https://emailoctopus.com/api-documentation/v2

Demonstrates how to make a request to the lists endpoint using curl and includes the necessary authentication header. Ensure your API token is correctly formatted.

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

--------------------------------

### Get List

Source: https://emailoctopus.com/api-documentation/v2

Retrieves the details of a specific list by its ID. This includes information about subscribers and list settings.

```APIDOC
## Get list 

##### path Parameters
list_idrequired| string Example:  00000000-0000-0000-0000-000000000000The ID of the list.  
---|---  
### Responses
**200**
Successful response
**400**
Bad request.
**401**
Unauthorized
**403**
Access denied.
**404**
Resource not found.
get/lists/{list_id}
https://api.emailoctopus.com/lists/{list_id}
###  Request samples 
  * Shell + Curl
  * Php + Curl
  * Node + Native
  * Javascript + Xhr
  * Java + Okhttp
  * Go + Native
  * Python + Python3


Copy
```
curl --request GET 
  --url https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000 
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

###  Response samples 
  * 200
  * 400
  * 401
  * 403
  * 404


Content type
application/json
Copy
Expand all  Collapse all 
`{
  * "id": "00000000-0000-0000-0000-000000000000",
  * "name": "New clients list",
  * "double_opt_in": false,
  * "fields": [
    * {
      * "label": "What is your hometown?",
      * "tag": "Hometown",
      * "type": "text",
      * "fallback": "Unknown"
}
],
  * "tags": [
    * "welcome"
],
  * "counts": [
    * {
      * "pending": 0,
      * "subscribed": 0,
      * "unsubscribed": 0
}
],
  * "created_at": "2015-12-01T12:59:37+00:00",
  * "last_updated_at": "2015-12-01T12:59:37+00:00"

}`
```

--------------------------------

### API Error Response Example

Source: https://emailoctopus.com/api-documentation/v2

This is an example of a typical error response when a request to the API is malformed or invalid. It includes details about the error type, status code, and specific validation issues.

```json
{
  "type": "https://emailoctopus.com/api-documentation/v2#bad-request",
  "title": "An error occurred.",
  "detail": "Bad request.",
  "status": 400,
  "errors": [
    {
      "pointer": "name",
      "parameter": "list_id",
      "detail": "This value should be between 1 and 100."
}
]

}
```

--------------------------------

### Contact Object Structure

Source: https://emailoctopus.com/api-documentation/v2

This is an example of a successful response when retrieving contacts. It shows the structure of the 'data' array, including individual contact details and pagination information.

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "email_address": "otto@example.com",
      "fields": {
        "referral": "Otto",
        "birthday": "2015-12-01",
        "how_many_pets": 2
},
      "tags": [
        "vip"
],
      "status": "subscribed",
      "created_at": "2015-12-01T12:59:37+00:00",
      "last_updated_at": "2015-12-01T12:59:37+00:00"
}
],
  "paging": {
    "next": {
      "url": "https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000/contacts?limit=10&starting_after=WzIsIjIwMjQtMDMtMTRUMTA6MTU6MjcrMDA6MDAiXQ",
      "starting_after": "WzIsIjIwMjQtMDMtMTRUMTA6MTU6MjcrMDA6MDAiXQ"
}
}

}
```

--------------------------------

### Campaign Summary Report Response Structure

Source: https://emailoctopus.com/api-documentation/v2

This is an example of a successful response for the campaign summary report, providing key metrics for a campaign.

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "sent": 200,
  "bounced": {
    "hard": 10,
    "soft": 5
},
  "opened": {
    "total": 110,
    "unique": 85
},
  "clicked": {
    "total": 110,
    "unique": 85
},
  "complained": 50,
  "unsubscribed": 25

}
```

--------------------------------

### Get All Tags (Shell + Curl)

Source: https://emailoctopus.com/api-documentation/v2

Use this cURL command to retrieve all tags for a specified list. Replace 'REPLACE_BEARER_TOKEN' with your actual API key.

```shell
curl --request GET \
  --url https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000/tags \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Requesting Next Page with Starting After Parameter

Source: https://emailoctopus.com/api-documentation/v2

This URL demonstrates how to request the next page of results by appending the 'starting_after' query string parameter to the API endpoint. Use the cursor exactly as provided in the previous response.

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

--------------------------------

### Get Campaign

Source: https://emailoctopus.com/api-documentation/v2

Retrieves details for a specific campaign using its ID.

```APIDOC
## Get campaign

### Description
Retrieves details for a specific campaign.

### Method
GET

### Endpoint
/campaigns/{campaign_id}

### Parameters
#### Path Parameters
- **campaign_id** (string) - Required - The ID of the campaign.

### Request Example
```curl
curl --request GET \
  --url https://api.emailoctopus.com/campaigns/00000000-0000-0000-0000-000000000000 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the campaign.
- **status** (string) - The status of the campaign.
- **name** (string) - The name of the campaign.
- **subject** (string) - The subject line of the campaign.
- **to** (array) - List of recipients.
- **from** (object) - Sender information.
- **content** (object) - Campaign content.
- **created_at** (string) - Timestamp when the campaign was created.
- **sent_at** (string) - Timestamp when the campaign was sent.

#### Response Example
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "draft",
  "name": "New clients campaign",
  "subject": "Hello",
  "to": [
    [
      "00000000-0000-0000-0000-000000000000"
    ]
  ],
  "from": {
    "name": "Otto Octopus",
    "email_address": "otto@example.com"
  },
  "content": {
    "html": "<html>Foo Bar</html>"
  },
  "created_at": "2015-12-01T12:59:37+00:00",
  "sent_at": "2015-12-01T12:59:37+00:00"
}
```
```

--------------------------------

### API Error Response Example

Source: https://emailoctopus.com/api-documentation/v2

Illustrates a typical error response from the API, including error type, title, detail, status code, and specific validation errors.

```json
{
  "type": "https://emailoctopus.com/api-documentation/v2#bad-request",
  "title": "An error occurred.",
  "detail": "Bad request.",
  "status": 400,
  "errors": [
    {
      "pointer": "name",
      "parameter": "list_id",
      "detail": "This value should be between 1 and 100."
    }
  ]
}
```

--------------------------------

### Get Campaign Details using cURL

Source: https://emailoctopus.com/api-documentation/v2

Use this cURL command to retrieve specific campaign details by providing the campaign ID. Ensure you replace the placeholder with your actual Bearer token.

```shell
curl --request GET \
  --url https://api.emailoctopus.com/campaigns/00000000-0000-0000-0000-000000000000 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Get All Lists - Shell/Curl

Source: https://emailoctopus.com/api-documentation/v2

Use this snippet to retrieve all lists associated with your EmailOctopus account. Ensure you replace 'REPLACE_BEARER_TOKEN' with your actual API key.

```shell
curl --request GET \
  --url https://api.emailoctopus.com/lists \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Get Campaign Summary Report (cURL)

Source: https://emailoctopus.com/api-documentation/v2

This cURL command fetches a summary report for a given campaign, including sent, bounced, opened, clicked, complained, and unsubscribed counts. Ensure you replace 'REPLACE_BEARER_TOKEN' with your valid API token.

```shell
curl --request GET \
  --url https://api.emailoctopus.com/campaigns/00000000-0000-0000-0000-000000000000/reports/summary \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Get Campaign Links Report (cURL)

Source: https://emailoctopus.com/api-documentation/v2

Use this cURL command to retrieve a report of all links clicked within a specific campaign. Replace 'REPLACE_BEARER_TOKEN' with your actual API key.

```shell
curl --request GET \
  --url https://api.emailoctopus.com/campaigns/00000000-0000-0000-0000-000000000000/reports/links \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Get Contact

Source: https://emailoctopus.com/api-documentation/v2

Retrieves details for a specific contact within a list. You can identify the contact by its ID or an MD5 hash of its email address.

```APIDOC
## Get Contact

### Description
Retrieves details for a specific contact within a list. You can identify the contact by its ID or an MD5 hash of its email address.

### Method
GET

### Endpoint
/lists/{list_id}/contacts/{contact_id}

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.
- **contact_id** (string) - Required - The ID of the contact, or an MD5 hash of the lowercase version of the contact's email address.

### Responses
#### Success Response (200)
Successful response.

#### Response Example
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "email_address": "otto@example.com",
  "fields": {
    "referral": "Otto",
    "birthday": "2015-12-01",
    "how_many_pets": 2
  },
  "tags": [
    "vip"
  ],
  "status": "subscribed",
  "created_at": "2015-12-01T12:59:37+00:00",
  "last_updated_at": "2015-12-01T12:59:37+00:00"
}
```
```

--------------------------------

### Get all tags for a list

Source: https://emailoctopus.com/api-documentation/v2

Retrieves a list of all tags assigned to contacts within a specified list. Supports pagination for large result sets.

```APIDOC
## GET /lists/{list_id}/tags

### Description
Retrieves all tags associated with a specific list. This endpoint allows for pagination to handle large numbers of tags.

### Method
GET

### Endpoint
`https://api.emailoctopus.com/lists/{list_id}/tags`

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list to retrieve tags from.

#### Query Parameters
- **limit** (integer) - Optional - Default: "100" - Specifies the maximum number of results to return per page.
- **starting_after** (string) - Optional - A cursor that points to the end of the page for retrieving subsequent results.

### Request Example
```shell
curl --request GET \
  --url https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000/tags \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

### Response
#### Success Response (200)
- **data** (array) - A list of tag objects.
  - **tag** (string) - The name of the tag.
- **paging** (object) - Contains information for pagination.
  - **next** (object) - Information about the next page of results.
    - **url** (string) - The URL to fetch the next page of results.
    - **starting_after** (string) - The cursor to use for fetching the next page.

#### Response Example
```json
{
  "data": [
    {
      "tag": "my tag"
    }
  ],
  "paging": {
    "next": {
      "url": "https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000/tags?limit=10&starting_after=WzIsIjIwMjQtMDMtMTRUMTA6MTU6MjcrMDA6MDAiXQ",
      "starting_after": "WzIsIjIwMjQtMDMtMTRUMTA6MTU6MjcrMDA6MDAiXQ"
    }
  }
}
```

#### Error Responses
- **400** - Bad request.
- **401** - Unauthorized.
- **403** - Access denied.
- **404** - Resource not found.
```

--------------------------------

### Get all lists

Source: https://emailoctopus.com/api-documentation/v2

Retrieves a paginated list of all contact lists associated with your EmailOctopus account. You can control the number of results per page and use a cursor for pagination.

```APIDOC
## Get all lists

### Description
Retrieves a paginated list of all contact lists. Allows control over results per page and pagination using a cursor.

### Method
GET

### Endpoint
https://api.emailoctopus.com/lists

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of results per page. Default: "100"
- **starting_after** (string) - Optional - Cursor that points to the end of the page for pagination.

### Request Example
```curl
curl --request GET \
  --url https://api.emailoctopus.com/lists \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

### Response
#### Success Response (200)
- **data** (array) - Contains a list of list objects.
  - **id** (string) - The unique identifier for the list.
  - **name** (string) - The name of the list.
  - **double_opt_in** (boolean) - Indicates if double opt-in is enabled for the list.
  - **fields** (array) - Custom fields configured for the list.
  - **tags** (array) - Tags associated with the list.
  - **counts** (object) - Counts of contacts in different states (pending, subscribed, unsubscribed).
  - **created_at** (string) - The timestamp when the list was created.
  - **last_updated_at** (string) - The timestamp when the list was last updated.
- **paging** (object) - Pagination information.
  - **next** (object) - Information about the next page of results.
    - **url** (string) - The URL to fetch the next page.
    - **starting_after** (string) - The cursor value for the next page.

#### Response Example (200)
```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "New clients list",
      "double_opt_in": false,
      "fields": [
        {
          "label": "What is your hometown?",
          "tag": "Hometown",
          "type": "text",
          "fallback": "Unknown"
        }
      ],
      "tags": [
        "welcome"
      ],
      "counts": [
        {
          "pending": 0,
          "subscribed": 0,
          "unsubscribed": 0
        }
      ],
      "created_at": "2015-12-01T12:59:37+00:00",
      "last_updated_at": "2015-12-01T12:59:37+00:00"
    }
  ],
  "paging": {
    "next": {
      "url": "https://api.emailoctopus.com/lists?limit=10&starting_after=WyJiOWYyNjA5OC1kZjcxLTExZWUtOTQ4Zi00Yjc0NTg4MjVjYzAiXQ",
      "starting_after": "WyJiOWYyNjA5OC1kZjcxLTExZWUtOTQ4Zi00Yjc0NTg4MjVjYzAiXQ"
    }
  }
}
```

#### Error Responses
- **400** - Bad request.
- **401** - Unauthorized.
```

--------------------------------

### Get Contacts using cURL

Source: https://emailoctopus.com/api-documentation/v2

Use this cURL command to retrieve a list of contacts from a specific list. Ensure you replace 'REPLACE_BEARER_TOKEN' with your actual API key.

```shell
curl --request GET \
  --url https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000/contacts \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Pagination Paging Attribute Example

Source: https://emailoctopus.com/api-documentation/v2

This JSON structure illustrates the 'paging' attribute returned in API responses for paginated collections. It includes a 'next' object with the URL and 'starting_after' cursor for fetching the subsequent page of results.

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

--------------------------------

### Get a specific contact

Source: https://emailoctopus.com/api-documentation/v2

Use this endpoint to retrieve details for a single contact within a list. Requires list ID and contact ID (or email hash).

```Shell
curl --request GET \
  --url https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000/contacts/631251b876fece73bc9dd647fe596d5f \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Get Campaign Contact Reports using cURL

Source: https://emailoctopus.com/api-documentation/v2

This cURL command fetches campaign contact reports for a specified status (e.g., 'bounced'). You can also use 'limit' and 'starting_after' parameters for pagination. Replace the placeholder with your actual Bearer token.

```shell
curl --request GET \
  --url 'https://api.emailoctopus.com/campaigns/00000000-0000-0000-0000-000000000000/reports?status=bounced' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### Get contacts

Source: https://emailoctopus.com/api-documentation/v2

Retrieves a list of contacts from a specified list. Supports filtering by various parameters like status, tags, and dates, as well as pagination.

```APIDOC
## GET /lists/{list_id}/contacts

### Description
Retrieves a list of contacts from a specified list. Supports filtering by various parameters like status, tags, and dates, as well as pagination.

### Method
GET

### Endpoint
https://api.emailoctopus.com/lists/{list_id}/contacts

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.

#### Query Parameters
- **limit** (integer) - Optional - Max number of results per page. Default: "100"
- **starting_after** (string) - Optional - Cursor that points to the end of the page.
- **tag** (string) - Optional - The tag associated with the contact.
- **status** (string) - Optional - The status of the contact. Enum: "subscribed" "unsubscribed" "pending". Default: "subscribed"
- **created_at.lte** (string) - Optional - Filter by creation date - less than or equal to. ISO 8601 date format.
- **created_at.gte** (string) - Optional - Filter by creation date - greater than or equal to. ISO 8601 date format.
- **last_updated_at.lte** (string) - Optional - Filter by update date - less than or equal to. ISO 8601 date format.
- **last_updated_at.gte** (string) - Optional - Filter by update date - greater than or equal to. ISO 8601 date format.

### Request Example
```curl
curl --request GET \
  --url https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000/contacts \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

### Responses
#### Success Response (200)
- **data** (array) - List of contacts.
  - **id** (string) - The unique identifier for the contact.
  - **email_address** (string) - The email address of the contact.
  - **fields** (object) - Custom fields associated with the contact.
  - **tags** (array) - List of tags applied to the contact.
  - **status** (string) - The subscription status of the contact.
  - **created_at** (string) - The date and time the contact was created.
  - **last_updated_at** (string) - The date and time the contact was last updated.
- **paging** (object) - Information for paginating through results.
  - **next** (object) - Details for fetching the next page of results.
    - **url** (string) - The URL for the next page.
    - **starting_after** (string) - The cursor for the next page.

#### Response Example
```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "email_address": "otto@example.com",
      "fields": {
        "referral": "Otto",
        "birthday": "2015-12-01",
        "how_many_pets": 2
      },
      "tags": [
        "vip"
      ],
      "status": "subscribed",
      "created_at": "2015-12-01T12:59:37+00:00",
      "last_updated_at": "2015-12-01T12:59:37+00:00"
    }
  ],
  "paging": {
    "next": {
      "url": "https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000/contacts?limit=10&starting_after=WzIsIjIwMjQtMDMtMTRUMTA6MTU6MjcrMDA6MDAiXQ",
      "starting_after": "WzIsIjIwMjQtMDMtMTRUMTA6MTU6MjcrMDA6MDAiXQ"
    }
  }
}
```
```

--------------------------------

### Get List Request (Curl)

Source: https://emailoctopus.com/api-documentation/v2

Use this cURL command to retrieve details of a specific email list. Replace 'REPLACE_BEARER_TOKEN' with your actual API key and '00000000-0000-0000-0000-000000000000' with the target list ID.

```bash
curl --request GET \
  --url https://api.emailoctopus.com/lists/00000000-0000-0000-0000-000000000000 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
```

--------------------------------

### API Error Response Example (400 Bad Request)

Source: https://emailoctopus.com/api-documentation/v2

This JSON structure represents a typical bad request error response from the API. It includes details about the error type, a general message, the HTTP status code, and specific validation errors with pointers to the problematic fields.

```JSON
{
  "type": "https://emailoctopus.com/api-documentation/v2#bad-request",
  "title": "An error occurred.",
  "detail": "Bad request.",
  "status": 400,
  "errors": [
    {
      "pointer": "name",
      "parameter": "list_id",
      "detail": "This value should be between 1 and 100."
    }
  ]

}
```

--------------------------------

### Delete Field Response (400 Bad Request)

Source: https://emailoctopus.com/api-documentation/v2

An example of a bad request response when attempting to delete a field, indicating an issue with the provided parameters, such as an invalid list ID format.

```json
{
  "type": "https://emailoctopus.com/api-documentation/v2#bad-request",
  "title": "An error occurred.",
  "detail": "Bad request.",
  "status": 400,
  "errors": [
    {
      "detail": "This value is not a valid UUID.",
      "parameter": "list_id"
    }
  ]
}
```

--------------------------------

### Create List

Source: https://emailoctopus.com/api-documentation/v2

Creates a new list within your EmailOctopus account. A list is a container for subscribers.

```APIDOC
## Create list

##### Request Body schema: application/json
optional
namerequired| string <= 255 characters  The name of the list.  
---|---  
### Responses
**201**
Successful response
**400**
Bad request.
**401**
Unauthorized
**403**
Access denied.
**422**
Unprocessable content.
post/lists
https://api.emailoctopus.com/lists
###  Request samples 
  * Payload
  * Shell + Curl
  * Php + Curl
  * Node + Native
  * Javascript + Xhr
  * Java + Okhttp
  * Go + Native
  * Python + Python3


Content type
application/json
Copy
`{
  * "name": "New clients list"

}`
###  Response samples 
  * 201
  * 400
  * 401
  * 403
  * 422


Content type
application/json
Copy
Expand all  Collapse all 
`{
  * "id": "00000000-0000-0000-0000-000000000000",
  * "name": "New clients list",
  * "double_opt_in": false,
  * "fields": [
    * {
      * "label": "What is your hometown?",
      * "tag": "Hometown",
      * "type": "text",
      * "fallback": "Unknown"
}
],
  * "tags": [
    * "welcome"
],
  * "counts": [
    * {
      * "pending": 0,
      * "subscribed": 0,
      * "unsubscribed": 0
}
],
  * "created_at": "2015-12-01T12:59:37+00:00",
  * "last_updated_at": "2015-12-01T12:59:37+00:00"

}`
```

--------------------------------

### Create contact

Source: https://emailoctopus.com/api-documentation/v2

Adds a new contact to a specified list. You can provide the contact's email address, custom fields, tags, and status.

```APIDOC
## Create contact

### Description
Adds a new contact to a specified list. You can provide the contact's email address, custom fields, tags, and status.

### Method
POST

### Endpoint
/lists/{list_id}/contacts

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.

#### Request Body
- **email_address** (string) - Required - The email address of the contact.
- **fields** (object) - Optional - An object containing key/value pairs of field values, using the field's tag as the key.
- **tags** (Array of strings) - Optional - An array of tags associated with the contact.
- **status** (string) - Optional - Enum: "pending" "subscribed" "unsubscribed" - The status of the contact.

### Request Example
```json
{
  "email_address": "otto@example.com",
  "fields": {
    "referral": "Otto",
    "birthday": "2015-12-01",
    "how_many_pets": 2,
    "fieldToRemove": null
  },
  "tags": [
    "vip"
  ],
  "status": "subscribed"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the created contact.
- **email_address** (string) - The email address of the contact.
- **fields** (object) - An object containing the contact's custom fields.
- **tags** (Array of strings) - An array of tags associated with the contact.
- **status** (string) - The status of the contact.
- **created_at** (string) - The timestamp when the contact was created.
- **last_updated_at** (string) - The timestamp when the contact was last updated.

#### Response Example
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "email_address": "otto@example.com",
  "fields": {
    "referral": "Otto",
    "birthday": "2015-12-01",
    "how_many_pets": 2
  },
  "tags": [
    "vip"
  ],
  "status": "subscribed",
  "created_at": "2015-12-01T12:59:37+00:00",
  "last_updated_at": "2015-12-01T12:59:37+00:00"
}
```
```

--------------------------------

### API Authentication Header

Source: https://emailoctopus.com/api-documentation/v2

Include this header in your requests to authenticate with the API. Replace {token} with your actual API key.

```http
Authorization: Bearer {token}
```

--------------------------------

### Create or Update Contact Response (200 OK)

Source: https://emailoctopus.com/api-documentation/v2

This is a successful response when a contact is created or updated. It returns the contact's ID, email address, fields, tags, status, and timestamps.

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "email_address": "otto@example.com",
  "fields": {
    "referral": "Otto",
    "birthday": "2015-12-01",
    "how_many_pets": 2
  },
  "tags": [
    "vip"
  ],
  "status": "subscribed",
  "created_at": "2015-12-01T12:59:37+00:00",
  "last_updated_at": "2015-12-01T12:59:37+00:00"
}
```

--------------------------------

### Create Tag

Source: https://emailoctopus.com/api-documentation/v2

Creates a new tag within a specified list. Tags can be used to segment your subscribers.

```APIDOC
## Create tag

### Description
Creates a new tag within a specified list.

### Method
POST

### Endpoint
/lists/{list_id}/tags

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.

#### Request Body
- **tag** (string) - Optional - The name of the tag.

### Request Example
```json
{
  "tag": "my tag"
}
```

### Response
#### Success Response (201)
- **tag** (string) - The name of the created tag.

#### Response Example
```json
{
  "tag": "my tag"
}
```
```

--------------------------------

### Create Email List Response (201)

Source: https://emailoctopus.com/api-documentation/v2

A successful response when creating a new email list. It includes the list's ID, name, opt-in status, custom fields, tags, subscriber counts, and timestamps.

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "New clients list",
  "double_opt_in": false,
  "fields": [
    {
      "label": "What is your hometown?",
      "tag": "Hometown",
      "type": "text",
      "fallback": "Unknown"
}
],
  "tags": [
    "welcome"
],
  "counts": [
    {
      "pending": 0,
      "subscribed": 0,
      "unsubscribed": 0
}
],
  "created_at": "2015-12-01T12:59:37+00:00",
  "last_updated_at": "2015-12-01T12:59:37+00:00"
}
```

--------------------------------

### Create or Update Contact

Source: https://emailoctopus.com/api-documentation/v2

This endpoint allows for the creation of a new contact if one does not exist, or the update of an existing contact within a specified list. It supports adding or removing tags, updating custom fields, and setting the contact's subscription status.

```APIDOC
## PUT /lists/{list_id}/contacts

### Description
This is an upsert endpoint. If the contact does not exist, it will be created. If the contact already exists, it will be updated.

### Method
PUT

### Endpoint
https://api.emailoctopus.com/lists/{list_id}/contacts

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.

#### Request Body
- **email_address** (string) - Required - The email address of the contact.
- **fields** (object) - Optional - An object containing key/value pairs of field values, using the field's tag as the key.
- **tags** (object) - Optional - An object containing key/value pairs, where the key is the tag name and the value is true to add the tag or false to remove it. Tags that are not referenced in the object will not be updated.
- **status** (string) - Optional - Enum: "pending" "subscribed" "unsubscribed" - The status of the contact.

### Request Example
```json
{
  "email_address": "otto@example.com",
  "fields": {
    "referral": "Otto",
    "birthday": "2015-12-01",
    "how_many_pets": 2,
    "fieldToRemove": null
  },
  "tags": {
    "vip": true,
    "tagToRemove": false
  },
  "status": "subscribed"
}
```

### Response
#### Success Response (200)
Successful response
- **id** (string) - The unique identifier for the contact.
- **email_address** (string) - The email address of the contact.
- **fields** (object) - An object containing the contact's custom field values.
- **tags** (array) - An array of tags associated with the contact.
- **status** (string) - The current status of the contact.
- **created_at** (string) - The timestamp when the contact was created.
- **last_updated_at** (string) - The timestamp when the contact was last updated.

#### Response Example
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "email_address": "otto@example.com",
  "fields": {
    "referral": "Otto",
    "birthday": "2015-12-01",
    "how_many_pets": 2
  },
  "tags": [
    "vip"
  ],
  "status": "subscribed",
  "created_at": "2015-12-01T12:59:37+00:00",
  "last_updated_at": "2015-12-01T12:59:37+00:00"
}
```

#### Error Responses
- **400** - Bad request.
- **401** - Unauthorized
- **403** - Access denied.
- **404** - Resource not found.
- **409** - Conflict.
- **422** - Unprocessable content.
```
Tokens:
Raw