EmailOctopus
App · 20 actions
Work with your EmailOctopus email marketing: manage lists, contacts, tags and custom fields, add or update subscribers, and list campaigns.
Actions
| Action | What it does |
|---|---|
| Add contact | Add a contact to a list. |
| Add or update contact | Add a contact to a list, or update it if the address is already there. |
| Create field | Add a custom field to a list: text, number, date, or a single or multiple choice. |
| Create list | Create an empty list. |
| Create tag | Add a tag to a list so contacts can be given it. |
| Delete contact | Remove a contact from a list for good. |
| Delete field | Delete a custom field from a list, with the values contacts hold in it. |
| Delete list | Delete a list and every contact on it. |
| Delete tag | Delete a tag from a list, taking it off every contact that has it. |
| Get contact | Get one contact on a list, by email address or id, with its custom field values, tags and status. |
| Get list | Get one list with its custom fields, tags, double opt-in setting and counts of pending, subscribed and unsubscribed contacts. |
| List campaigns | List the account's campaigns with their status, subject and sender. |
| List contacts | List the contacts on a list, filtered by status, tag, and when they were added or last changed. |
| List lists | List the account's lists with their fields, tags and contact counts. |
| List tags | List the tags on a list. |
| Rename list | Change a list's name. |
| Rename tag | Rename a tag on a list. |
| Update contact | Change a contact's email address, custom field values, tags or status. |
| Update field | Change a text, number or date field's label or fallback value. |
| Update many contacts | Change up to 100 contacts of one list in a single request. |
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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Email address
email_addresstextRequired - The contact's email address.
- Custom field values
fieldsobject - Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
- Tags
tagslist - Tags to put on the new contact. New tags are created.
- Status
statustext - 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
contactobject- The contact
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Email address
email_addresstextRequired - The contact's email address.
- Custom field values
fieldsobject - Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
- Tags to add
add_tagslist - Tags to put on the contact. New tags are created.
- Tags to remove
remove_tagslist - Tags to take off the contact.
- Status
statustext - 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
contactobject- The contact
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Label
labeltextRequired - The field's name as people see it.
- Tag
tagtextRequired - The short name used to refer to the field in emails and when adding contacts. It cannot be changed later.
- Type
typetextRequired - What the field holds.One of:
text,number,date,choice_single(Single choice),choice_multiple(Multiple choice). - Choices
choiceslist - The options people choose from. Only for the two choice types.
- Fallback value
fallbacktext - What emails show when a contact has no value for the field.
Outputs
fieldobject- The custom field
Example output
{
"field": {
"choices": [],
"fallback": "Unknown",
"label": "Favourite colour",
"tag": "FavouriteColour",
"type": "text"
}
}Create list
Create an empty list.
Inputs
- Name
nametextRequired - The list's name, up to 255 characters.
Outputs
listobject- The list
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Tag
tagtextRequired - The tag's name, up to 255 characters.
Outputs
tagobject- The tag
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Contact
contacttextRequired - The contact's email address, or its id from 'List contacts' or an earlier step.
Outputs
contacttext- The contact deleted, as given
deletedtrue/false- Always true once deleted
list_idtext- The list the contact was on
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Field
tagtextRequired - The custom field. Pick one from the list, or type its tag.
Outputs
deletedtrue/false- Always true once deleted
list_idtext- The list the field was on
tagtext- The field deleted
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
Outputs
deletedtrue/false- Always true once deleted
list_idtext- The list deleted
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Tag
tagtextRequired - The tag. Pick one from the list, or type its name.
Outputs
deletedtrue/false- Always true once deleted
list_idtext- The list the tag was on
tagtext- The tag deleted
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Contact
contacttextRequired - The contact's email address, or its id from 'List contacts' or an earlier step.
Outputs
contactobject- The contact
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
Outputs
listobject- The list
Example output
{
"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
limitnumber - How many to return, 1 to 100. EmailOctopus's default is 100.From 1 to 100.
- Next page cursor
starting_aftertext - The 'next_cursor' from an earlier page, to get the page after it.
Outputs
campaignslist- The campaigns
countnumber- How many on this page
next_cursortext- Pass as 'starting after' for the next page; empty on the last one
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Status
statustext - Only contacts with this status. Defaults to subscribed.One of:
subscribed,pending(Pending (waiting to confirm)),unsubscribed. - Tag
tagtext - Only contacts with this tag.
- Added on or after
created_fromdate - Only contacts added on or after this date.
- Added on or before
created_todate - Only contacts added on or before this date.
- Changed on or after
updated_fromdate - Only contacts last changed on or after this date.
- Changed on or before
updated_todate - Only contacts last changed on or before this date.
- Page size
limitnumber - How many to return, 1 to 100. EmailOctopus's default is 100.From 1 to 100.
- Next page cursor
starting_aftertext - The 'next_cursor' from an earlier page, to get the page after it.
Outputs
contactslist- The contacts
countnumber- How many on this page
list_idtext- The list read
next_cursortext- Pass as 'starting after' for the next page; empty on the last one
Example output
{
"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
limitnumber - How many to return, 1 to 100. EmailOctopus's default is 100.From 1 to 100.
- Next page cursor
starting_aftertext - The 'next_cursor' from an earlier page, to get the page after it.
Outputs
countnumber- How many on this page
listslist- The lists
next_cursortext- Pass as 'starting after' for the next page; empty on the last one
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Page size
limitnumber - How many to return, 1 to 100. EmailOctopus's default is 100.From 1 to 100.
- Next page cursor
starting_aftertext - The 'next_cursor' from an earlier page, to get the page after it.
Outputs
countnumber- How many on this page
next_cursortext- Pass as 'starting after' for the next page; empty on the last one
tag_nameslist- Just the tag names, for a later step
tagslist- The tags
Example output
{
"count": 1,
"next_cursor": "",
"tag_names": [
"vip"
],
"tags": [
{
"tag": "vip"
}
]
}Rename list
Change a list's name.
Inputs
- List
list_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- New name
nametextRequired - The list's new name, up to 255 characters.
Outputs
listobject- The list
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Tag
tagtextRequired - The tag. Pick one from the list, or type its name.
- New name
new_tagtextRequired - The tag's new name.
Outputs
previous_tagtext- The tag's old name
tagobject- The tag, under its new name
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Contact
contacttextRequired - The contact's email address, or its id from 'List contacts' or an earlier step.
- New email address
email_addresstext - Change the contact's email address. Leave empty to keep it.
- Custom field values
fieldsobject - Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
- Tags to add
add_tagslist - Tags to put on the contact. New tags are created.
- Tags to remove
remove_tagslist - Tags to take off the contact.
- Status
statustext - 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
contactobject- The contact
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Field
tagtextRequired - The custom field. Pick one from the list, or type its tag.
- New label
labeltext - A new label. Leave empty to keep it.
- New fallback value
fallbacktext - A new fallback value. Leave empty to keep it.
Outputs
fieldobject- The custom field
Example output
{
"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_idtextRequired - The EmailOctopus list. Pick one, or give its id from an earlier step.
- Contacts
contactslistRequired - 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_countnumber- How many failed
errorslist- The contacts that could not be changed, with the reason
updatedlist- The contacts that were changed
updated_countnumber- How many were changed
Example output
{
"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
}