# EmailOctopus

> Work with your EmailOctopus email marketing: manage lists, contacts, tags and custom fields, add or update subscribers, and list campaigns.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/emailoctopus

## Actions

### Add contact

Add a contact to a list. It fails if the address is already on the list; use 'Add or update contact' to change an existing one.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Email address (`email_address`, text, required): The contact's email address.
- Custom field values (`fields`, object): Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
- Tags (`tags`, list): Tags to put on the new contact. New tags are created.
- Status (`status`, text): Whether the contact receives campaigns. Leave empty to keep the current status (a new contact is subscribed, or pending on a double opt-in list). One of: `subscribed`, `pending` (Pending (waiting to confirm)), `unsubscribed`.

**Outputs**

- `contact` (object): The contact

**Example output**

```json
{
  "contact": {
    "created_at": "2026-10-01T09:00:00+00:00",
    "email_address": "jo@example.com",
    "fields": {
      "FirstName": "Jo"
    },
    "id": "00000000-0000-0000-0000-000000000002",
    "last_updated_at": "2026-10-15T09:00:00+00:00",
    "status": "subscribed",
    "tags": [
      "vip"
    ]
  }
}
```

### Add or update contact

Add a contact to a list, or update it if the address is already there. Only what you give changes.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Email address (`email_address`, text, required): The contact's email address.
- Custom field values (`fields`, object): Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
- Tags to add (`add_tags`, list): Tags to put on the contact. New tags are created.
- Tags to remove (`remove_tags`, list): Tags to take off the contact.
- Status (`status`, text): Whether the contact receives campaigns. Leave empty to keep the current status (a new contact is subscribed, or pending on a double opt-in list). One of: `subscribed`, `pending` (Pending (waiting to confirm)), `unsubscribed`.

**Outputs**

- `contact` (object): The contact

**Example output**

```json
{
  "contact": {
    "created_at": "2026-10-01T09:00:00+00:00",
    "email_address": "jo@example.com",
    "fields": {
      "FirstName": "Jo"
    },
    "id": "00000000-0000-0000-0000-000000000002",
    "last_updated_at": "2026-10-15T09:00:00+00:00",
    "status": "subscribed",
    "tags": [
      "vip"
    ]
  }
}
```

### Create field

Add a custom field to a list: text, number, date, or a single or multiple choice.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Label (`label`, text, required): The field's name as people see it.
- Tag (`tag`, text, required): The short name used to refer to the field in emails and when adding contacts. It cannot be changed later.
- Type (`type`, text, required): What the field holds. One of: `text`, `number`, `date`, `choice_single` (Single choice), `choice_multiple` (Multiple choice).
- Choices (`choices`, list): The options people choose from. Only for the two choice types.
- Fallback value (`fallback`, text): What emails show when a contact has no value for the field.

**Outputs**

- `field` (object): The custom field

**Example output**

```json
{
  "field": {
    "choices": [],
    "fallback": "Unknown",
    "label": "Favourite colour",
    "tag": "FavouriteColour",
    "type": "text"
  }
}
```

### Create list

Create an empty list.

**Inputs**

- Name (`name`, text, required): The list's name, up to 255 characters.

**Outputs**

- `list` (object): The list

**Example output**

```json
{
  "list": {
    "counts": {
      "pending": 0,
      "subscribed": 12,
      "unsubscribed": 1
    },
    "created_at": "2026-10-01T09:00:00+00:00",
    "double_opt_in": false,
    "fields": [
      {
        "choices": [],
        "fallback": null,
        "label": "First name",
        "tag": "FirstName",
        "type": "text"
      }
    ],
    "id": "00000000-0000-0000-0000-000000000001",
    "last_updated_at": "2026-10-15T09:00:00+00:00",
    "name": "Newsletter",
    "tags": [
      "vip"
    ]
  }
}
```

### Create tag

Add a tag to a list so contacts can be given it.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Tag (`tag`, text, required): The tag's name, up to 255 characters.

**Outputs**

- `tag` (object): The tag

**Example output**

```json
{
  "tag": {
    "tag": "vip"
  }
}
```

### Delete contact

Remove a contact from a list for good. To keep the contact but stop emailing them, set the status to unsubscribed instead.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Contact (`contact`, text, required): The contact's email address, or its id from 'List contacts' or an earlier step.

**Outputs**

- `contact` (text): The contact deleted, as given
- `deleted` (true/false): Always true once deleted
- `list_id` (text): The list the contact was on

**Example output**

```json
{
  "contact": "jo@example.com",
  "deleted": true,
  "list_id": "00000000-0000-0000-0000-000000000001"
}
```

### Delete field

Delete a custom field from a list, with the values contacts hold in it.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Field (`tag`, text, required): The custom field. Pick one from the list, or type its tag.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `list_id` (text): The list the field was on
- `tag` (text): The field deleted

**Example output**

```json
{
  "deleted": true,
  "list_id": "00000000-0000-0000-0000-000000000001",
  "tag": "FavouriteColour"
}
```

### Delete list

Delete a list and every contact on it. This cannot be undone.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `list_id` (text): The list deleted

**Example output**

```json
{
  "deleted": true,
  "list_id": "00000000-0000-0000-0000-000000000001"
}
```

### Delete tag

Delete a tag from a list, taking it off every contact that has it.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Tag (`tag`, text, required): The tag. Pick one from the list, or type its name.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `list_id` (text): The list the tag was on
- `tag` (text): The tag deleted

**Example output**

```json
{
  "deleted": true,
  "list_id": "00000000-0000-0000-0000-000000000001",
  "tag": "vip"
}
```

### Get contact

Get one contact on a list, by email address or id, with its custom field values, tags and status.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Contact (`contact`, text, required): The contact's email address, or its id from 'List contacts' or an earlier step.

**Outputs**

- `contact` (object): The contact

**Example output**

```json
{
  "contact": {
    "created_at": "2026-10-01T09:00:00+00:00",
    "email_address": "jo@example.com",
    "fields": {
      "FirstName": "Jo"
    },
    "id": "00000000-0000-0000-0000-000000000002",
    "last_updated_at": "2026-10-15T09:00:00+00:00",
    "status": "subscribed",
    "tags": [
      "vip"
    ]
  }
}
```

### Get list

Get one list with its custom fields, tags, double opt-in setting and counts of pending, subscribed and unsubscribed contacts.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.

**Outputs**

- `list` (object): The list

**Example output**

```json
{
  "list": {
    "counts": {
      "pending": 0,
      "subscribed": 12,
      "unsubscribed": 1
    },
    "created_at": "2026-10-01T09:00:00+00:00",
    "double_opt_in": false,
    "fields": [
      {
        "choices": [],
        "fallback": null,
        "label": "First name",
        "tag": "FirstName",
        "type": "text"
      }
    ],
    "id": "00000000-0000-0000-0000-000000000001",
    "last_updated_at": "2026-10-15T09:00:00+00:00",
    "name": "Newsletter",
    "tags": [
      "vip"
    ]
  }
}
```

### List campaigns

List the account's campaigns with their status, subject and sender. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Page size (`limit`, number): How many to return, 1 to 100. EmailOctopus's default is 100. From 1 to 100.
- Next page cursor (`starting_after`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `campaigns` (list): The campaigns
- `count` (number): How many on this page
- `next_cursor` (text): Pass as 'starting after' for the next page; empty on the last one

**Example output**

```json
{
  "campaigns": [
    {
      "content": {
        "html": "<p>Hello</p>"
      },
      "created_at": "2026-10-10T09:00:00+00:00",
      "from": {
        "email_address": "jo@example.com",
        "name": "Jo Bloggs"
      },
      "id": "00000000-0000-0000-0000-000000000003",
      "name": "October news",
      "preview_text": "Read our latest news",
      "sent_at": "2026-10-12T09:00:00+00:00",
      "status": "sent",
      "subject": "What's new in October",
      "to": [
        "00000000-0000-0000-0000-000000000001"
      ]
    }
  ],
  "count": 1,
  "next_cursor": ""
}
```

### List contacts

List the contacts on a list, filtered by status, tag, and when they were added or last changed. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Status (`status`, text): Only contacts with this status. Defaults to subscribed. One of: `subscribed`, `pending` (Pending (waiting to confirm)), `unsubscribed`.
- Tag (`tag`, text): Only contacts with this tag.
- Added on or after (`created_from`, date): Only contacts added on or after this date.
- Added on or before (`created_to`, date): Only contacts added on or before this date.
- Changed on or after (`updated_from`, date): Only contacts last changed on or after this date.
- Changed on or before (`updated_to`, date): Only contacts last changed on or before this date.
- Page size (`limit`, number): How many to return, 1 to 100. EmailOctopus's default is 100. From 1 to 100.
- Next page cursor (`starting_after`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `contacts` (list): The contacts
- `count` (number): How many on this page
- `list_id` (text): The list read
- `next_cursor` (text): Pass as 'starting after' for the next page; empty on the last one

**Example output**

```json
{
  "contacts": [
    {
      "created_at": "2026-10-01T09:00:00+00:00",
      "email_address": "jo@example.com",
      "fields": {
        "FirstName": "Jo"
      },
      "id": "00000000-0000-0000-0000-000000000002",
      "last_updated_at": "2026-10-15T09:00:00+00:00",
      "status": "subscribed",
      "tags": [
        "vip"
      ]
    }
  ],
  "count": 1,
  "list_id": "00000000-0000-0000-0000-000000000001",
  "next_cursor": ""
}
```

### List lists

List the account's lists with their fields, tags and contact counts. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Page size (`limit`, number): How many to return, 1 to 100. EmailOctopus's default is 100. From 1 to 100.
- Next page cursor (`starting_after`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `lists` (list): The lists
- `next_cursor` (text): Pass as 'starting after' for the next page; empty on the last one

**Example output**

```json
{
  "count": 1,
  "lists": [
    {
      "counts": {
        "pending": 0,
        "subscribed": 12,
        "unsubscribed": 1
      },
      "created_at": "2026-10-01T09:00:00+00:00",
      "double_opt_in": false,
      "fields": [
        {
          "choices": [],
          "fallback": null,
          "label": "First name",
          "tag": "FirstName",
          "type": "text"
        }
      ],
      "id": "00000000-0000-0000-0000-000000000001",
      "last_updated_at": "2026-10-15T09:00:00+00:00",
      "name": "Newsletter",
      "tags": [
        "vip"
      ]
    }
  ],
  "next_cursor": ""
}
```

### List tags

List the tags on a list. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Page size (`limit`, number): How many to return, 1 to 100. EmailOctopus's default is 100. From 1 to 100.
- Next page cursor (`starting_after`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_cursor` (text): Pass as 'starting after' for the next page; empty on the last one
- `tag_names` (list): Just the tag names, for a later step
- `tags` (list): The tags

**Example output**

```json
{
  "count": 1,
  "next_cursor": "",
  "tag_names": [
    "vip"
  ],
  "tags": [
    {
      "tag": "vip"
    }
  ]
}
```

### Rename list

Change a list's name.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- New name (`name`, text, required): The list's new name, up to 255 characters.

**Outputs**

- `list` (object): The list

**Example output**

```json
{
  "list": {
    "counts": {
      "pending": 0,
      "subscribed": 12,
      "unsubscribed": 1
    },
    "created_at": "2026-10-01T09:00:00+00:00",
    "double_opt_in": false,
    "fields": [
      {
        "choices": [],
        "fallback": null,
        "label": "First name",
        "tag": "FirstName",
        "type": "text"
      }
    ],
    "id": "00000000-0000-0000-0000-000000000001",
    "last_updated_at": "2026-10-15T09:00:00+00:00",
    "name": "Weekly news",
    "tags": [
      "vip"
    ]
  }
}
```

### Rename tag

Rename a tag on a list. Contacts keep it under the new name.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Tag (`tag`, text, required): The tag. Pick one from the list, or type its name.
- New name (`new_tag`, text, required): The tag's new name.

**Outputs**

- `previous_tag` (text): The tag's old name
- `tag` (object): The tag, under its new name

**Example output**

```json
{
  "previous_tag": "vip",
  "tag": {
    "tag": "gold"
  }
}
```

### Update contact

Change a contact's email address, custom field values, tags or status. Only what you give changes.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Contact (`contact`, text, required): The contact's email address, or its id from 'List contacts' or an earlier step.
- New email address (`email_address`, text): Change the contact's email address. Leave empty to keep it.
- Custom field values (`fields`, object): Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
- Tags to add (`add_tags`, list): Tags to put on the contact. New tags are created.
- Tags to remove (`remove_tags`, list): Tags to take off the contact.
- Status (`status`, text): Whether the contact receives campaigns. Leave empty to keep the current status (a new contact is subscribed, or pending on a double opt-in list). One of: `subscribed`, `pending` (Pending (waiting to confirm)), `unsubscribed`.

**Outputs**

- `contact` (object): The contact

**Example output**

```json
{
  "contact": {
    "created_at": "2026-10-01T09:00:00+00:00",
    "email_address": "jo@example.com",
    "fields": {
      "FirstName": "Jo"
    },
    "id": "00000000-0000-0000-0000-000000000002",
    "last_updated_at": "2026-10-15T09:00:00+00:00",
    "status": "unsubscribed",
    "tags": [
      "vip"
    ]
  }
}
```

### Update field

Change a text, number or date field's label or fallback value. Choice fields cannot be changed through the API.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Field (`tag`, text, required): The custom field. Pick one from the list, or type its tag.
- New label (`label`, text): A new label. Leave empty to keep it.
- New fallback value (`fallback`, text): A new fallback value. Leave empty to keep it.

**Outputs**

- `field` (object): The custom field

**Example output**

```json
{
  "field": {
    "choices": [],
    "fallback": "Unknown",
    "label": "Colour",
    "tag": "FavouriteColour",
    "type": "text"
  }
}
```

### Update many contacts

Change up to 100 contacts of one list in a single request. Each needs its id and what to change; contacts that fail are reported without stopping the rest.

**Inputs**

- List (`list_id`, text, required): The EmailOctopus list. Pick one, or give its id from an earlier step.
- Contacts (`contacts`, list, required): The contacts to change, each with its 'id' and any of 'email_address', 'fields', 'status' and 'tags' (tag names with true to add or false to remove), for example [{"id": "...", "status": "unsubscribed"}]. Up to 100.

**Outputs**

- `error_count` (number): How many failed
- `errors` (list): The contacts that could not be changed, with the reason
- `updated` (list): The contacts that were changed
- `updated_count` (number): How many were changed

**Example output**

```json
{
  "error_count": 0,
  "errors": [],
  "updated": [
    {
      "created_at": "2026-10-01T09:00:00+00:00",
      "email_address": "jo@example.com",
      "fields": {
        "FirstName": "Jo"
      },
      "id": "00000000-0000-0000-0000-000000000002",
      "last_updated_at": "2026-10-15T09:00:00+00:00",
      "status": "subscribed",
      "tags": [
        "vip"
      ]
    }
  ],
  "updated_count": 1
}
```
