# EmailOctopus

EmailOctopus is an email marketing platform founded in 2015, offering affordable and intuitive solutions for individuals and businesses to connect with their subscribers.

- **Category:** email newsletters
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 20
- **Triggers:** 0
- **Slug:** `EMAILOCTOPUS`
- **Version:** 20260217_00

## Tools

### Create Contact

**Slug:** `EMAILOCTOPUS_CREATE_CONTACT`

This tool creates a new contact in EmailOctopus. The tool will add a contact to a specified list with the provided information.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | array | No | Tags to associate with the contact for segmentation and filtering purposes. |
| `fields` | object | No | Custom field values for the contact. Keys should be field tags (e.g., 'FirstName', 'LastName'). Use the 'Get All Lists' action to see available field tags for a list. |
| `status` | string | No | The subscription status of the contact. Accepted values: 'subscribed', 'unsubscribed', or 'pending' (case-insensitive). Defaults to 'subscribed' if not provided. |
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list to add the contact to. Use the 'Get All Lists' action to retrieve available list IDs. |
| `email_address` | string | Yes | The email address of the contact to create. Must be a valid email format. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Field

**Slug:** `EMAILOCTOPUS_CREATE_FIELD`

Tool to create a new custom field on an EmailOctopus mailing list. Use when you need to add additional data fields beyond the default Email, First Name, and Last Name fields.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | Yes | The tag used to reference this field in templates and API calls (e.g., 'Company', 'PhoneNumber'). Should be unique within the list. |
| `type` | string ("text" | "number" | "date") | Yes | The data type of the custom field. Use 'text' for strings, 'number' for numeric values, or 'date' for dates. |
| `label` | string | Yes | The display label for the custom field (e.g., 'Company', 'Phone Number'). This is what users will see in forms and settings. |
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list to add the custom field to. Use the 'Get All Lists' action to retrieve available list IDs. |
| `fallback` | string | No | Default value to use when the field is empty. This value will be used in email templates when no value is provided for a contact. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create List

**Slug:** `EMAILOCTOPUS_CREATE_LIST`

Creates a new mailing list in EmailOctopus for organizing and managing email contacts. The list is created with default fields (Email address, First name, Last name) and can be used to add contacts, send campaigns, and track subscriber engagement.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | The name of the new mailing list. Must be between 2-255 characters. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Tag

**Slug:** `EMAILOCTOPUS_CREATE_TAG`

Tool to create a new tag on an EmailOctopus mailing list. Use when you need to add a new tag for contact segmentation and filtering purposes.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | Yes | The name of the tag to create. Used for segmentation and filtering contacts within the list. |
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list to create the tag in. Use the 'Get All Lists' action to retrieve available list IDs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Contact

**Slug:** `EMAILOCTOPUS_DELETE_CONTACT`

Permanently deletes a contact from a specified EmailOctopus list. This action is irreversible - once deleted, the contact and all associated data will be removed from the list. Use this for list management, honoring deletion requests, and data privacy compliance (e.g., GDPR right to erasure).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list containing the contact. Use the 'Get All Lists' action to retrieve available list IDs. |
| `contact_id` | string | Yes | The unique identifier (UUID) of the contact to delete, or an MD5 hash of the lowercase version of the contact's email address. Use the 'Create Contact' action response or list contacts to find contact IDs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Field

**Slug:** `EMAILOCTOPUS_DELETE_FIELD`

Permanently deletes a custom field from a specified EmailOctopus list. This action is irreversible - once deleted, the field and all associated data will be removed from the list. Use this for list customization and field management.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | Yes | A unique identifier for the custom field to delete (e.g., 'Hometown', 'TestDeleteField'). This is the field tag, not the field name. |
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list containing the field. Use the 'Get All Lists' action to retrieve available list IDs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete List

**Slug:** `EMAILOCTOPUS_DELETE_LIST`

This tool allows you to delete an existing mailing list from your EmailOctopus account. Once a list is deleted, it cannot be recovered, and all contacts within the list will be permanently removed. Note: Lists can only be deleted if no contacts within the list have received an email in the last 7 days.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `list_id` | string | Yes | The unique identifier of the list to be deleted |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Tag

**Slug:** `EMAILOCTOPUS_DELETE_TAG`

Tool to delete a tag from a mailing list in EmailOctopus. Use when you need to remove an existing tag that is no longer needed for contact organization or segmentation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | Yes | A unique identifier for the tag to be deleted |
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list containing the tag |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get All Lists

**Slug:** `EMAILOCTOPUS_GET_ALL_LISTS`

This tool retrieves all the mailing lists associated with the EmailOctopus account.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of lists to return per page. Defaults to 100 if not specified. |
| `starting_after` | string | No | Cursor for pagination. Use the 'starting_after' value from the previous response's paging.next object to retrieve the next page of results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contact

**Slug:** `EMAILOCTOPUS_GET_CONTACT`

Tool to retrieve details of a specific contact from an EmailOctopus list. Use when you need to fetch contact information including email, fields, tags, and subscription status.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list containing the contact. Use the 'Get All Lists' action to retrieve available list IDs. |
| `contact_id` | string | Yes | The unique identifier (UUID) of the contact, or an MD5 hash of the lowercase version of the contact's email address. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get List

**Slug:** `EMAILOCTOPUS_GET_LIST`

Retrieves details of a specific mailing list by ID. Use when you need to fetch list information, including its name, fields, tags, contact counts, and opt-in settings.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `list_id` | string | Yes | The unique identifier (UUID) of the list to retrieve |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Recent Campaigns

**Slug:** `EMAILOCTOPUS_GET_RECENT_CAMPAIGNS`

This tool retrieves a list of recent campaigns from the EmailOctopus account.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of campaigns to return per page (1-100, default 100) |
| `starting_after` | string | No | Cursor token for pagination. Use the 'starting_after' value from the previous response's paging.next to fetch the next page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Contacts

**Slug:** `EMAILOCTOPUS_LIST_CONTACTS`

Tool to retrieve contacts from an EmailOctopus list. Returns a paginated list of contacts with optional filtering by tag, status, and date ranges.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | No | Filter contacts by a specific tag. Only contacts with this tag will be returned. |
| `limit` | integer | No | Maximum number of contacts to return per page (1-100, default 100) |
| `status` | string ("subscribed" | "unsubscribed" | "pending") | No | Filter contacts by subscription status. Defaults to 'subscribed' if not specified. |
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list. Use the 'Get All Lists' action to retrieve available list IDs. |
| `created_at_gte` | string | No | Filter by creation date - greater than or equal to. Must be in ISO 8601 format (e.g., 2024-01-19T12:14:28Z). |
| `created_at_lte` | string | No | Filter by creation date - less than or equal to. Must be in ISO 8601 format (e.g., 2024-01-19T12:14:28Z). |
| `starting_after` | string | No | Cursor token for pagination. Use the 'starting_after' value from the previous response's paging.next to fetch the next page. |
| `last_updated_at_gte` | string | No | Filter by last update date - greater than or equal to. Must be in ISO 8601 format (e.g., 2024-01-19T12:14:28Z). |
| `last_updated_at_lte` | string | No | Filter by last update date - less than or equal to. Must be in ISO 8601 format (e.g., 2024-01-19T12:14:28Z). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Tags

**Slug:** `EMAILOCTOPUS_LIST_TAGS`

Tool to retrieve all tags from a mailing list. Use when you need to see what tags are available on a specific list for contact segmentation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of tags to return per page. Defaults to 100 if not specified. |
| `list_id` | string | Yes | The unique identifier (UUID) of the mailing list to retrieve tags from. Use the 'Get All Lists' action to retrieve available list IDs. |
| `starting_after` | string | No | Cursor for pagination. Use the 'starting_after' value from the previous response's paging.next object to retrieve the next page of results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unsubscribe Contact

**Slug:** `EMAILOCTOPUS_UNSUBSCRIBE_CONTACT`

Unsubscribes a contact from an EmailOctopus mailing list. This tool updates the contact's subscription status to 'unsubscribed', which stops them from receiving future emails from the specified list. The contact record is preserved but marked as unsubscribed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list containing the contact. Use 'Get All Lists' to retrieve available list IDs. |
| `contact_id` | string | Yes | The unique identifier (UUID) of the contact to unsubscribe. Use 'Get All Contacts' or 'Create Contact' to obtain contact IDs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Batch Update Contacts

**Slug:** `EMAILOCTOPUS_UPDATE_CONTACTS_BATCH`

Tool to update multiple contacts in an EmailOctopus list in a single batch operation. Use when you need to efficiently update multiple contacts at once with changes to their email, fields, status, or tags.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list containing the contacts to update. Use 'Get All Lists' to retrieve available list IDs. |
| `contacts` | array | Yes | Array of contacts to update. Each contact must have an 'id' field. Other fields (email_address, fields, status, tags) are optional and will only update if provided. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Field

**Slug:** `EMAILOCTOPUS_UPDATE_FIELD`

Updates an existing custom field on an EmailOctopus list including its label, tag, type, and fallback value. Use this action to modify field properties or rename field tags. Note that changing the tag will affect how the field is referenced in email templates.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | Yes | The tag identifier for the field. This can be the same as current_tag to keep it unchanged, or a new value to rename the field tag. Must be a unique identifier. |
| `type` | string ("text" | "number" | "date") | Yes | The type of the field. Determines what kind of data can be stored. |
| `label` | string | Yes | A human-readable label for the field. This is what users will see when filling out forms. |
| `list_id` | string | Yes | The unique identifier (UUID) of the list containing the field to update. Use the 'Get All Lists' action to retrieve available list IDs. |
| `fallback` | string | No | A default value for the field, used in campaigns when there is no other value available. Set to null or omit to remove the fallback value. |
| `current_tag` | string | Yes | The current tag identifier of the field to update (e.g., 'Hometown', 'TestUpdateField'). This identifies which field to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update List

**Slug:** `EMAILOCTOPUS_UPDATE_LIST`

Tool to update an existing mailing list's name in EmailOctopus. Use when you need to rename a list.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | The new name for the mailing list. Must be between 2-255 characters. |
| `list_id` | string | Yes | The unique identifier (UUID) of the list to update |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Tag

**Slug:** `EMAILOCTOPUS_UPDATE_TAG`

Tool to update an existing tag on a mailing list. Use when you need to rename a tag.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | Yes | The current name of the tag to update. This is the existing tag identifier. |
| `list_id` | string | Yes | The unique identifier (UUID) of the list containing the tag to update. Use the 'Get All Lists' action to retrieve available list IDs. |
| `new_tag` | string | Yes | The new name to assign to the tag. This will replace the existing tag name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create or Update Contact

**Slug:** `EMAILOCTOPUS_UPSERT_CONTACT`

Tool to create or update a contact in EmailOctopus. If the contact does not exist, it will be created. If the contact already exists, it will be updated. Use when you need to ensure a contact exists with specific information regardless of whether they're already in the list.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | object | No | An object containing key/value pairs for tag management. Set tag name as key and true to add the tag or false to remove it. Tags not referenced in this object will not be updated. |
| `fields` | object | No | Custom field values for the contact. Keys should be field tags (e.g., 'FirstName', 'LastName'). Values can be text (string), number (integer), date (string in ISO format), or null to unset a field. Use the 'Get All Lists' action to see available field tags for a list. |
| `status` | string | No | The subscription status of the contact. Accepted values: 'subscribed', 'unsubscribed', or 'pending' (case-insensitive). If not provided, defaults to the contact's current status (for updates) or 'subscribed' (for new contacts). |
| `list_id` | string | Yes | The unique identifier (UUID) of the EmailOctopus list. Use the 'Get All Lists' action to retrieve available list IDs. |
| `email_address` | string | Yes | The email address of the contact to create or update. Must be a valid email format. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |