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

ActionWhat it does
Add contactAdd a contact to a list.
Add or update contactAdd a contact to a list, or update it if the address is already there.
Create fieldAdd a custom field to a list: text, number, date, or a single or multiple choice.
Create listCreate an empty list.
Create tagAdd a tag to a list so contacts can be given it.
Delete contactRemove a contact from a list for good.
Delete fieldDelete a custom field from a list, with the values contacts hold in it.
Delete listDelete a list and every contact on it.
Delete tagDelete a tag from a list, taking it off every contact that has it.
Get contactGet one contact on a list, by email address or id, with its custom field values, tags and status.
Get listGet one list with its custom fields, tags, double opt-in setting and counts of pending, subscribed and unsubscribed contacts.
List campaignsList the account's campaigns with their status, subject and sender.
List contactsList the contacts on a list, filtered by status, tag, and when they were added or last changed.
List listsList the account's lists with their fields, tags and contact counts.
List tagsList the tags on a list.
Rename listChange a list's name.
Rename tagRename a tag on a list.
Update contactChange a contact's email address, custom field values, tags or status.
Update fieldChange a text, number or date field's label or fallback value.
Update many contactsChange 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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
Email addressemail_addresstextRequired
The contact's email address.
Custom field valuesfieldsobject
Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
Tagstagslist
Tags to put on the new contact. New tags are created.
Statusstatustext
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
Email addressemail_addresstextRequired
The contact's email address.
Custom field valuesfieldsobject
Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
Tags to addadd_tagslist
Tags to put on the contact. New tags are created.
Tags to removeremove_tagslist
Tags to take off the contact.
Statusstatustext
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
LabellabeltextRequired
The field's name as people see it.
TagtagtextRequired
The short name used to refer to the field in emails and when adding contacts. It cannot be changed later.
TypetypetextRequired
What the field holds.One of: text, number, date, choice_single (Single choice), choice_multiple (Multiple choice).
Choiceschoiceslist
The options people choose from. Only for the two choice types.
Fallback valuefallbacktext
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

NamenametextRequired
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
TagtagtextRequired
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
ContactcontacttextRequired
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
FieldtagtextRequired
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

Listlist_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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
TagtagtextRequired
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
ContactcontacttextRequired
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

Listlist_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 sizelimitnumber
How many to return, 1 to 100. EmailOctopus's default is 100.From 1 to 100.
Next page cursorstarting_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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
Statusstatustext
Only contacts with this status. Defaults to subscribed.One of: subscribed, pending (Pending (waiting to confirm)), unsubscribed.
Tagtagtext
Only contacts with this tag.
Added on or aftercreated_fromdate
Only contacts added on or after this date.
Added on or beforecreated_todate
Only contacts added on or before this date.
Changed on or afterupdated_fromdate
Only contacts last changed on or after this date.
Changed on or beforeupdated_todate
Only contacts last changed on or before this date.
Page sizelimitnumber
How many to return, 1 to 100. EmailOctopus's default is 100.From 1 to 100.
Next page cursorstarting_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 sizelimitnumber
How many to return, 1 to 100. EmailOctopus's default is 100.From 1 to 100.
Next page cursorstarting_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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
Page sizelimitnumber
How many to return, 1 to 100. EmailOctopus's default is 100.From 1 to 100.
Next page cursorstarting_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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
New namenametextRequired
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
TagtagtextRequired
The tag. Pick one from the list, or type its name.
New namenew_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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
ContactcontacttextRequired
The contact's email address, or its id from 'List contacts' or an earlier step.
New email addressemail_addresstext
Change the contact's email address. Leave empty to keep it.
Custom field valuesfieldsobject
Each custom field's tag with its value, for example {"FirstName": "Jo"}. Fields not given are left as they are.
Tags to addadd_tagslist
Tags to put on the contact. New tags are created.
Tags to removeremove_tagslist
Tags to take off the contact.
Statusstatustext
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
FieldtagtextRequired
The custom field. Pick one from the list, or type its tag.
New labellabeltext
A new label. Leave empty to keep it.
New fallback valuefallbacktext
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

Listlist_idtextRequired
The EmailOctopus list. Pick one, or give its id from an earlier step.
ContactscontactslistRequired
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
}

On this page