Menu

Mattering Automations EmailOctopus integration

Connect EmailOctopus to Mattering Automations: contact lists, contacts with an email-keyed upsert, custom fields, tags and the full campaign reporting surface as workflow steps, authenticated with one v2 API key. Campaigns are read only, because EmailOctopus does not support sending over its API.

The Mattering Automations EmailOctopus integration puts the EmailOctopus v2 API on your automation canvas: create and rename contact lists, list and read contacts, create them, upsert them by email address, update them singly or in bulk, delete them, manage custom fields and tags, and read campaigns together with every campaign report EmailOctopus produces. Thirty two nodes in total, seventeen that read and fifteen that act.

One thing shapes the whole integration and it is better read now than discovered later: EmailOctopus does not support sending over its API. The vendor's own position is that all emails sent through EmailOctopus need to be created directly in the Dashboard, and the API has no campaign create, update, send, test send or schedule operation to work around it. Campaigns in this integration are read only. The single node that can cause EmailOctopus to send anything is EmailOctopus: Start Automation For Contact, which queues one contact into an automation you built in the dashboard, and it is flagged destructive for that reason.

The credential is one API key sent as an Authorization: Bearer header. The step that catches people is which key: EmailOctopus runs an older 1.6 API alongside v2, and a key created before v2 shipped is labelled legacy in the account and is rejected by v2 with an ordinary 401. Create a new key rather than reusing the one an older integration already has. The rest of this page is the setup walkthrough, the node reference, how to work with the eight campaign report segments and the email-address addressing, and the failures worth recognising on sight.

Before you start

  • An EmailOctopus account. The Starter plan is described by EmailOctopus as free forever and its published limitations name no API restriction, so a free account can use this integration properly. Those limitations are 2,500 contacts, 10,000 emails a month, campaign reports available for 30 days, one user, 10 custom fields and 10 tags per list, three automations of up to five steps each, one landing page and one form, no subscriber profile editing, and a required EmailOctopus link in campaigns.
  • A NEW EmailOctopus API key, created for this connection rather than copied from an existing integration. EmailOctopus states that a key created before the release of API v2, labelled legacy, needs replacing, and that new API keys are compatible with all versions of the API.
  • An understanding that the key is account-wide. It is not scoped to a list, so one credential reaches every list, contact, campaign and report in the account, including every subscriber email address. Decide who holds it accordingly.
  • Campaigns you want to report on must already have been created and sent in the EmailOctopus dashboard. Nothing in this integration can create or send one, and the report nodes only return data for campaigns that have actually gone out.
  • For EmailOctopus: Start Automation For Contact, an automation built in the EmailOctopus dashboard whose trigger type is set to Started via API. Without that trigger type the contact is not accepted. Note too that a contact can enter a given automation only once unless you enable repeats on the automation, so a deliberate re-run does nothing until you change that setting.
  • A Mattering workspace with access to the Automations app.

Create an EmailOctopus API key

EmailOctopus v2 authenticates with a single API key sent as an Authorization: Bearer header against api.emailoctopus.com. There is no OAuth flow, no account id to look up and no per-list scoping. The one decision worth making carefully is to create a NEW key rather than reuse an old one, because EmailOctopus's v2 release drew a hard line: the vendor states that a key created before that release, labelled legacy, has to be replaced, and that new API keys are compatible with all versions of the API. So a new key serves both, and an old one serves only the older 1.6 API.

Sign in to EmailOctopus and open the API keys screen in your account's developer settings, where keys are created and listed.
Look at what is already there. If a key is marked legacy, leave it alone rather than copying it. It is still doing its job for whatever older integration uses the 1.6 API, and it cannot authenticate against v2.
Click Add key, give it a name that says where it will be used, and create it. Copy the value before you leave the screen: EmailOctopus shows a new key once.
This key is account-wide. It reaches every list, every contact and every campaign report in the account, and the contacts it can read and delete are real people's email addresses. Store it in the Mattering credential store rather than in a spreadsheet or a shared document, and revoke it in EmailOctopus if it is ever exposed.
A legacy key and a wrong key produce the SAME response: an ordinary HTTP 401. There is nothing in the error to tell you the key is valid and merely too old, which is why people re-copy a key that was never mistyped. If a key you are confident about fails, mint a new one before debugging anything else.

Connect EmailOctopus to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose EmailOctopus from the list.
Click Create new credential, give it a name that says which EmailOctopus account it belongs to, and paste the key into the API Key field.
Save the credential and click Test Connection. Mattering calls the EmailOctopus lists endpoint, which is the same call EmailOctopus's own authentication documentation tells you to make to confirm a key works. It takes no parameters, changes nothing and is safe to repeat.
A green result means the key is live and the header wiring is correct. A 401 means either a wrong key or a legacy key, and the two are indistinguishable from the response, so try a freshly minted key before looking anywhere else.

Verify it works

Open any automation canvas and check the palette: an EmailOctopus section should list seventeen read nodes and fifteen action nodes. Drop EmailOctopus: List Contact Lists onto the canvas and run a test step. It takes no parameters, so it is the natural probe: it proves the credential end to end and returns the list ids that almost every other node in this connector needs, along with each list's name, its double opt-in setting, its custom field definitions, its tag names and its contact counts split into pending, subscribed and unsubscribed.

Now open the List picker on a node such as EmailOctopus: List Contacts and confirm it populates with your real list names. The pickers are fed by EmailOctopus: List Contact Lists, so a working picker is a second confirmation that the credential is fine. Two lists genuinely can share a name, which is why the picker shows the list id underneath each one.

Run EmailOctopus: List Contacts against a list and read the result carefully, because there is a default here worth knowing about before you build on it. EmailOctopus defaults the status filter to subscribed, so leaving the Status field blank returns subscribed contacts only and silently hides pending and unsubscribed ones. Set it explicitly when you want the whole list. Everything in this verify path is read-only and cannot reach any of the delete nodes, so it is safe to re-run whenever you want to check the connection.

Node reference

32 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 17

EmailOctopus: Campaign Bounced For

emailoctopus_list_campaign_bounced_contacts

List the contacts whose delivery bounced. Worth feeding back into your own records: a repeatedly bouncing address costs sender reputation on every future campaign. Each row carries contact_id, contact_email_address and occurred_at, so it feeds straight into a contact update or an automation trigger. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false. On a free EmailOctopus account campaign reports are kept for 30 days after the send, so an older campaign returns nothing there.

EmailOctopus: Campaign Clicked By

emailoctopus_list_campaign_clicked_contacts

List the contacts who clicked a link in it. Use Get Campaign Link Report alongside this to see WHICH links were clicked. Each row carries contact_id, contact_email_address and occurred_at, so it feeds straight into a contact update or an automation trigger. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false. On a free EmailOctopus account campaign reports are kept for 30 days after the send, so an older campaign returns nothing there.

EmailOctopus: Campaign Complained About

emailoctopus_list_campaign_complained_contacts

List the contacts who marked it as spam. The most damaging outcome in this list and the one to act on first. Each row carries contact_id, contact_email_address and occurred_at, so it feeds straight into a contact update or an automation trigger. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false. On a free EmailOctopus account campaign reports are kept for 30 days after the send, so an older campaign returns nothing there.

EmailOctopus: Campaign Not Clicked By

emailoctopus_list_campaign_not_clicked_contacts

List the contacts who did NOT click any link. Narrower than not-opened and usually the better re-engagement segment, because it includes people who read the email and did nothing. Each row carries contact_id, contact_email_address and occurred_at, so it feeds straight into a contact update or an automation trigger. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false. On a free EmailOctopus account campaign reports are kept for 30 days after the send, so an older campaign returns nothing there.

EmailOctopus: Campaign Not Opened By

emailoctopus_list_campaign_not_opened_contacts

List the contacts who did NOT open it. This is the re-engagement segment, and it is the reason the eight statuses are eight nodes: asking who ignored a campaign is a completely different job from asking who read it. Each row carries contact_id, contact_email_address and occurred_at, so it feeds straight into a contact update or an automation trigger. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false. On a free EmailOctopus account campaign reports are kept for 30 days after the send, so an older campaign returns nothing there.

EmailOctopus: Campaign Opened By

emailoctopus_list_campaign_opened_contacts

List the contacts who opened it. Open tracking is a loaded tracking pixel, so treat it as a soft signal: an image-blocking client suppresses it and a privacy proxy can fire it without a human reading anything. Each row carries contact_id, contact_email_address and occurred_at, so it feeds straight into a contact update or an automation trigger. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false. On a free EmailOctopus account campaign reports are kept for 30 days after the send, so an older campaign returns nothing there.

EmailOctopus: Campaign Sent To

emailoctopus_list_campaign_sent_contacts

List every contact the campaign was delivered to. This is the denominator for every other report on this campaign. Each row carries contact_id, contact_email_address and occurred_at, so it feeds straight into a contact update or an automation trigger. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false. On a free EmailOctopus account campaign reports are kept for 30 days after the send, so an older campaign returns nothing there.

EmailOctopus: Campaign Unsubscribed From

emailoctopus_list_campaign_unsubscribed_contacts

List the contacts who unsubscribed from it. EmailOctopus has already stopped sending to them; read this to keep your own systems in step. Each row carries contact_id, contact_email_address and occurred_at, so it feeds straight into a contact update or an automation trigger. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false. On a free EmailOctopus account campaign reports are kept for 30 days after the send, so an older campaign returns nothing there.

EmailOctopus: Get Campaign

emailoctopus_get_campaign

Read one campaign: status (draft, sending, sent or error), name, subject, the sender name and address, the list ids it went to, its HTML content, and when it was created and sent. EmailOctopus does not support sending over the API: every campaign has to be created and sent in the EmailOctopus dashboard, so this connector reads campaigns and never creates or sends one.

EmailOctopus: Get Campaign Link Report

emailoctopus_get_campaign_link_report

List every tracked link in one sent campaign with its total and unique click counts, so you can see WHICH call to action worked rather than only how many people clicked something. Unlike the other report nodes this one is NOT paged: it returns the whole set of links under data with no paging key. On a free account reports are kept for 30 days after the send.

EmailOctopus: Get Campaign Summary Report

emailoctopus_get_campaign_summary_report

Get the headline numbers for one sent campaign in a single call: sent, bounced split into hard and soft, opened and clicked each split into total and unique, complained and unsubscribed. Opens and clicks are nested objects rather than flat numbers, so read opened.unique rather than opened. This is one row about one campaign, not a time series: to chart performance over time, collect it per campaign and key by the campaign's sent_at. On a free account reports are kept for 30 days after the send.

EmailOctopus: Get Contact

emailoctopus_get_contact

Read one contact by id or by email address, returning its custom field values, tags, subscription status and both timestamps. Because an email address is accepted directly, this is the node to use for a does-this-person-exist check: a missing contact answers 404 with a not-found error type rather than an empty success.

EmailOctopus: Get List

emailoctopus_get_list

Read one list: its name, its double opt-in setting, its full custom field definitions (label, tag, type, choices and fallback), its tag names, and its contact counts split into pending, subscribed and unsubscribed. This node is also what populates the field picker on the update and delete field nodes, because EmailOctopus publishes no separate fields lister.

EmailOctopus: List Campaigns

emailoctopus_list_campaigns

List the campaigns in the account, newest first, with their status, subject, sender, target list ids and rendered HTML. EmailOctopus does not support sending over the API: every campaign has to be created and sent in the EmailOctopus dashboard, so this connector reads campaigns and never creates or sends one. Use this to find a campaign id for the report nodes, or to mirror send history into your own systems. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false.

EmailOctopus: List Contact Lists

emailoctopus_list_lists

List every contact list in the account with its name, whether double opt-in is on, its custom field definitions, its tag names and its contact counts by status. This is the node every list picker in the connector reads from, so it runs whenever a config panel opens. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false.

EmailOctopus: List Contacts

emailoctopus_list_contacts

List the contacts in a list, optionally filtered by tag, by subscription status, and by creation or last-update date. Note the status filter DEFAULTS TO subscribed on the vendor's side, so leaving it blank hides unsubscribed and pending contacts; set it explicitly when you want them. Each row carries the contact's id, email address, custom field values, tags, status and both timestamps. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false.

EmailOctopus: List Tags

emailoctopus_list_tags

List the tags defined on a list. Each row is a single tag key carrying the tag's name. Tags are list-specific labels applied to contacts, used to segment a campaign's audience and to trigger automations. This node is what populates the tag pickers elsewhere in the connector. Paged by an opaque forward-only cursor. The response carries paging.next.starting_after; pass that value back in starting_after for the next page, exactly as it was returned. There is no previous cursor, no page number and no total. The last page is the one with NO paging.next key at all, so a loop must stop on the ABSENCE of that key rather than on a flag turning false.

Action nodes 15

EmailOctopus: Create Contact

emailoctopus_create_contact

Add a new contact to a list. Fails with an already-exists error if the address is already on the list, so for anything a workflow might retry prefer EmailOctopus: Create Or Update Contact, which upserts instead. Note the difference in the tags argument between the two: this node takes a plain ARRAY of tag names to apply, while the update-shaped nodes take an OBJECT of name to true or false. If the list has double opt-in enabled, a contact created as subscribed still receives the confirmation step. A free account stores up to 2,500 contacts and returns an out-of-limits error beyond that.

EmailOctopus: Create Field

emailoctopus_create_field

Add a custom field to a list, so contacts can carry data beyond their email address and campaigns can merge it into copy. The tag is the token you write into an email; the label is what a human sees on a signup form. The two choice types REQUIRE a choices array and the other three must not have one. A free account allows 10 fields per list and returns an out-of-limits error at the eleventh.

EmailOctopus: Create List

emailoctopus_create_list

Create an empty contact list. Name is the only thing the API accepts at creation: double opt-in, fields and tags are configured afterwards, fields and tags through this connector's own nodes and double opt-in in the dashboard. The response carries the new list's id, which is what every other node in this connector needs.

EmailOctopus: Create Or Update Contact

emailoctopus_upsert_contact

Create the contact if the address is new, update it if the address is already on the list. This is the node most sync workflows want: it is keyed on the email address rather than on an id, so nothing has to be looked up first, and a retried step produces the same result as the first attempt instead of an already-exists error. Tags here are an OBJECT of name to true or false, and tags you do not mention are left alone, so a partial update never wipes a contact's other labels. A field value of null clears that field.

EmailOctopus: Create Tag

emailoctopus_create_tag

Define a new tag on a list. This creates the tag itself and applies it to nobody; attach it to contacts with the contact create and update nodes. Creating a tag that already exists returns an already-exists error, so check EmailOctopus: List Tags first in a workflow that might run twice. A free account allows 10 tags per list.

EmailOctopus: Delete Contact

emailoctopus_delete_contact

PERMANENTLY DELETE A CONTACT from a list, addressed by id or by email address. There is no undo, and deleting also erases the record that this person unsubscribed, so a later re-import can put them back on the list and email them again. To stop sending to somebody, set their status to unsubscribed with EmailOctopus: Update Contact instead; delete only when the record itself has to go, such as an erasure request. Returns 204 No Content with an empty body.

EmailOctopus: Delete Field

emailoctopus_delete_field

PERMANENTLY DELETE A CUSTOM FIELD from a list, along with every contact's value for it. There is no undo. Any campaign or automation still merging this field's tag will render nothing where the value used to be, so check your live templates first. Returns 204 No Content with an empty body. field_tag is the FIELD's tag, not a contact tag.

EmailOctopus: Delete List

emailoctopus_delete_list

PERMANENTLY DELETE A LIST AND EVERY CONTACT IN IT. There is no undo and no confirmation step on this API, and the contacts go with the list along with their subscription history, so a re-import is not the same thing as a restore. Returns 204 No Content with an empty body. Prefer unsubscribing contacts, or renaming and abandoning a list, unless the deletion is genuinely intended.

EmailOctopus: Delete Tag

emailoctopus_delete_tag

PERMANENTLY DELETE A TAG from a list and remove it from every contact carrying it. There is no undo, and any automation triggered by this tag stops firing. The contacts themselves are untouched; only the label goes. Returns 204 No Content with an empty body. tag_name is a contact tag, not a custom field's tag.

EmailOctopus: Rename Tag

emailoctopus_update_tag

Rename a tag across the whole list. tag_name is what the tag is called today and new_tag is what it becomes. Every contact carrying it moves with the rename, and so does any automation triggered by it, but anything OUTSIDE EmailOctopus that references the old name (this connector's own nodes included) keeps pointing at a name that no longer exists, so update those in the same pass.

EmailOctopus: Start Automation For Contact

emailoctopus_start_automation

CAN SEND REAL EMAIL, AND CANNOT BE RECALLED. Queue one contact into an automation that was built in the EmailOctopus dashboard. This is the ONLY node in the connector that can cause EmailOctopus to send anything: EmailOctopus does not support sending over the API: every campaign has to be created and sent in the EmailOctopus dashboard, so this connector reads campaigns and never creates or sends one. The automation must be set to the Started via API trigger type, or the contact is not accepted. A contact can only trigger a given automation ONCE unless Allow contacts to repeat is enabled in that automation's settings, which makes a retried workflow step safe by default and also means a deliberate re-run does nothing until that setting is changed. The automation id is not available from any endpoint on this API, so copy it from the automation's URL in the dashboard. Returns 204 No Content with an empty body on success. A free account allows 3 automations of up to 5 steps each.

EmailOctopus: Update Contact

emailoctopus_update_contact

Update an existing contact addressed by id or by its current email address. This is the node that can CHANGE an address: identify the contact by the address it has now and pass the new one in email_address. Everything is optional, tags are an object of name to true or false, and anything omitted is left alone, so this is safe to run with only the one attribute you mean to change. Setting status to unsubscribed here is a real unsubscribe.

EmailOctopus: Update Contacts In Bulk

emailoctopus_update_contacts_batch

Update many contacts in one request, which is how to stay inside the 10 requests per second rate limit when syncing a large set. Every entry MUST carry an id: unlike the single update nodes this one is not keyed on email address and does NOT accept an address in place of an id, so hash or look up first if all you hold are addresses. The response is PARTIAL SUCCESS by design: successes land under data.success and failures under data.errors with a per-contact status, type and detail, and the call as a whole still answers HTTP 200. Check data.errors rather than the status code. This endpoint updates only; it creates nothing.

EmailOctopus: Update Field

emailoctopus_update_field

Update a custom field's label, tag, type or fallback. field_tag identifies the field as it is called TODAY and new_tag is what it will be called afterwards, so a rename sets both. Renaming a tag changes the key that contact field values are written under and the token that campaign copy merges, so update your own workflows and any live campaign templates in the same pass. Changing a field's type can drop values that no longer parse.

EmailOctopus: Update List

emailoctopus_update_list

Rename a list. Name is the only mutable property on this endpoint; a list's fields and tags are changed through the field and tag nodes, and double opt-in is a dashboard setting.

Using the integration

Campaigns are read only, and what to do instead

The API this integration is built on has no send operation, so nothing here creates, schedules, tests or sends a campaign. EmailOctopus's own position is that all emails sent through EmailOctopus need to be created directly in the Dashboard. What the integration does instead is the two halves either side of the send: EmailOctopus: Create Or Update Contact and its siblings keep the list correct from whatever system owns your customer records, and the campaign report nodes read back what a send actually did. The practical shape of a campaign workflow is therefore a schedule that runs after a send rather than a workflow that performs one. The single exception is EmailOctopus: Start Automation For Contact, covered below.

The one node that can send real mail

EmailOctopus: Start Automation For Contact queues one contact into an automation built in the EmailOctopus dashboard, and whatever that automation does next is real mail to a real person that cannot be recalled. The node is flagged destructive and opens its description saying so. Two constraints go with it. The automation must have its trigger type set to Started via API, or the contact is not accepted at all. And by default a contact can enter a given automation only once, which quietly makes a retried workflow step safe, and equally quietly makes a deliberate second run do nothing until repeats are enabled on the automation in the dashboard. Both halves are worth knowing before you conclude the node is broken.

The eight campaign report segments

EmailOctopus v2 has one campaign reports path with a required status parameter, and this integration turns it into eight named nodes: EmailOctopus: Campaign Sent To, EmailOctopus: Campaign Opened By, EmailOctopus: Campaign Not Opened By, EmailOctopus: Campaign Clicked By, EmailOctopus: Campaign Not Clicked By, EmailOctopus: Campaign Bounced For, EmailOctopus: Campaign Complained About and EmailOctopus: Campaign Unsubscribed From. Each pins its own status internally rather than exposing it as a field, so it cannot be mistyped. Every row carries the contact id, the contact's email address and when the event happened, which is what makes these outputs feed straight into a contact update. For per-link detail rather than per-person detail, use EmailOctopus: Get Campaign Link Report, and for the headline numbers use EmailOctopus: Get Campaign Summary Report, where opens and clicks are nested objects, so read opened.unique rather than opened.

Addressing contacts by email address

EmailOctopus identifies a contact by its id or by the MD5 hash of its LOWERCASED email address. Hashing an address exactly as it arrived, with its original capitalisation, produces a different digest that returns a clean 404, and that 404 is indistinguishable from a contact who genuinely does not exist. Because addresses arriving from forms, CRM exports and webhooks carry mixed case eventually, this connector strips, lowercases and hashes for you on EmailOctopus: Get Contact, EmailOctopus: Update Contact, EmailOctopus: Delete Contact and EmailOctopus: Start Automation For Contact. Paste a raw address or wire one in from an earlier step and it resolves. A value that is already an id or an already-computed digest passes through untouched rather than being hashed twice. EmailOctopus: Update Contacts In Bulk is the exception: the API requires a real id on every entry there and documents no address addressing, so the connector does not invent it.

Create, upsert, and the difference in the tags argument

EmailOctopus: Create Contact fails with an already-exists error when the address is already on the list, which makes it the wrong node for anything a workflow might retry. EmailOctopus: Create Or Update Contact is the one most sync workflows want: it creates when the address is new and updates when it is not, keyed on the address rather than on an id, so a retried step produces the same result as the first attempt. The two differ in one argument that is easy to get wrong. On the create node, tags are a plain ARRAY of tag names to apply. On the upsert and update nodes, tags are an OBJECT mapping a tag name to true or false, and a tag you do not mention is left as it is, which is what lets you add one tag without clearing the rest.

Paging, and why bulk update exists

Paged reads use an opaque forward-only cursor. A response carries paging.next.starting_after, you pass that value back in Starting After for the next page, and the last page is the one with no paging.next key at all. There is no previous link, no page number, no total and no has-more flag, so a loop must terminate on ABSENCE rather than on a flag turning false, and a loop written the other way never stops. The vendor asks that the cursor not be deconstructed. A response holds at most 100 results. Five reads page this way: EmailOctopus: List Campaigns, EmailOctopus: List Contact Lists, EmailOctopus: List Contacts, EmailOctopus: List Tags and the eight report nodes. EmailOctopus: Get Campaign Link Report does not page at all and returns the whole set of links in one response. Separately, the rate limit is a token bucket: EmailOctopus documents a bucket holding up to 100 tokens, replenished at 10 per second, with one token consumed per request, so a steady 10 requests a second or a burst of 100, and its help centre says exceeding it returns HTTP 429 and blocks the connection for up to a minute. That is why EmailOctopus: Update Contacts In Bulk exists: one request revising many contacts is how a large sync stays inside the budget instead of a loop of single updates.

Fields and tags are different things that look alike

A custom FIELD has a tag, and a contact TAG is also called a tag, and EmailOctopus's own API documentation describes the two path parameters identically. They are not related. A field's tag is the token you merge into campaign copy, such as Hometown, and it is managed with EmailOctopus: Create Field, EmailOctopus: Update Field and EmailOctopus: Delete Field. A contact tag is a label used to segment an audience and trigger automations, and it is managed with EmailOctopus: Create Tag, EmailOctopus: Rename Tag and EmailOctopus: Delete Tag. This integration keeps them apart in the configuration too: the field nodes read their picker from a list's field definitions and the tag nodes read theirs from the list's tags, so a field will never appear in a tag picker.

The deletes, and what has no undo

Four nodes delete permanently and none of them has an undo. EmailOctopus: Delete List takes the list and every contact in it, along with their subscription history, so a re-import is not a restore. EmailOctopus: Delete Contact erases the record that the person unsubscribed, which means a later import can put them back on the list and mail them again, so setting a contact's status to unsubscribed with EmailOctopus: Update Contact is nearly always what a workflow actually wanted. EmailOctopus: Delete Field takes every contact's value for that field, and any live campaign template still merging its tag renders nothing where the value used to be. EmailOctopus: Delete Tag removes the label from every contact carrying it and stops any automation triggered by it from firing. Each of those nodes names its reversible alternative in its own description.

On the automation canvas

Drag an EmailOctopus node onto a canvas, attach the credential once, and wire it to schedules, conditions, AI steps and every other connector in the workspace. This integration ships no trigger nodes, so an EmailOctopus workflow is started by a schedule or by an event somewhere else, such as a signup in your own product or a form submission, and reads from or writes to EmailOctopus as a step. If you want push rather than polling, EmailOctopus publishes webhooks for contact events such as created, updated, unsubscribed, bounced and complained. They are configured in the EmailOctopus dashboard rather than through the API, which is why there are no nodes for them here, and one can be pointed at a webhook trigger on a Mattering automation. Credentials are held in the workspace credential store, so the key is entered once rather than by each person who builds a workflow.

From AI assistants over MCP

These nodes are also exposed over MCP, an open protocol for connecting AI assistants to tools, so Claude, ChatGPT and any other MCP-capable assistant can work with EmailOctopus through your Mattering workspace. Matter, the assistant built into the platform, uses the same nodes natively. Given that this connector reads real subscriber addresses and can delete them permanently, the sensible split is to expose the reads and the upsert to an assistant and keep the four deletes and EmailOctopus: Start Automation For Contact behind a condition or a human approval step.

Troubleshooting

Test Connection returns 401 with a key you are sure is correct
The likeliest cause is a legacy key. EmailOctopus keys created before the v2 release are labelled legacy in the account and authenticate only against the older 1.6 API, and v2 rejects them with an ordinary HTTP 401 carrying the same invalid-key body a completely wrong key produces. Nothing in the response distinguishes the two, so re-copying the key does not help. Open your EmailOctopus API key settings, create a NEW key, paste that into the credential and test again. New keys work with every version of the API, so the old integration that depends on the legacy key is unaffected either way. If a brand new key also fails, check that you pasted the whole value with no trailing space.
A palette search for a send or schedule node finds nothing
There is no send node, and this is not an omission. EmailOctopus does not support sending over its API and states that all emails sent through EmailOctopus need to be created directly in the Dashboard, so there is no campaign create, update, send, test send or schedule operation to build a node on. Campaigns in this integration are read only. Build and send the campaign in EmailOctopus, then use EmailOctopus: List Campaigns and the report nodes to read what it did. If what you actually want is automated mail to individuals, the route is an automation built in the dashboard with the Started via API trigger type, driven by EmailOctopus: Start Automation For Contact.
A contact you know exists returns 404 when looked up by email address
Three usual causes, in order of likelihood. First, the address is on a different list: contacts are list-scoped, so EmailOctopus: Get Contact needs the list the person is actually on. Second, there is a stray space or a different address entirely, since a plus-addressed or aliased variant is a different contact as far as EmailOctopus is concerned. Third, if you are calling EmailOctopus directly elsewhere and comparing, note that EmailOctopus hashes the LOWERCASED address, so a hash computed over the original capitalisation returns a 404 that looks identical to a missing contact. This connector lowercases before hashing, so it is not the cause here, but it is why the direct call and the node can disagree.
A contact list looks short, or unsubscribed contacts are missing
EmailOctopus: List Contacts leaves the Status field blank by default and EmailOctopus defaults that parameter on its side to subscribed, so a blank status returns subscribed contacts only and hides pending and unsubscribed ones. Set the status explicitly when you want them. If the count still looks wrong, remember the response is paged by an opaque forward-only cursor: one call returns one page, and there is no total in the response to compare against. Read the whole list by following paging.next.starting_after until the response arrives with no paging.next key at all.
A report node returns nothing for a campaign you definitely sent
Check three things. The campaign must have a status of sent, since draft and sending campaigns have no report to read. On a free EmailOctopus account campaign reports are available for 30 days after the send, so an older campaign returns nothing rather than an error, and that is a plan limit rather than something this connector can change. And confirm you have the right node for the question: the eight segment nodes each return people, EmailOctopus: Get Campaign Summary Report returns the headline counts, and EmailOctopus: Get Campaign Link Report returns per-link clicks. An empty result from EmailOctopus: Campaign Complained About on a healthy campaign is a good outcome rather than a fault.
Creating a field or a tag fails with an out-of-limits error
This is a plan ceiling rather than a connector fault. On the free Starter plan EmailOctopus allows 10 custom fields and 10 tags per list, and the API answers past that with an out-of-limits error rather than failing quietly. The same class of limit applies elsewhere on that plan: 2,500 contacts stored and three automations. Read EmailOctopus: Get List to see the list's current field and tag definitions, remove what is no longer used, or move to a paid plan. Check EmailOctopus's own pricing page for the current numbers.
Creating a contact fails with an already-exists error on a step that is being retried
EmailOctopus: Create Contact is not idempotent by design: it refuses an address that is already on the list. Swap it for EmailOctopus: Create Or Update Contact, which is keyed on the email address and creates or updates as appropriate, so a retried step produces the same result as the first attempt. Note one difference when you switch: on the create node, tags are a plain array of names, while on the upsert and update nodes they are an object mapping a tag name to true or false, and a tag you do not mention is left alone. EmailOctopus: Create Tag behaves the same way, so check with EmailOctopus: List Tags first in a workflow that might run twice.
A bulk update rejects entries that the single update node accepts
EmailOctopus: Update Contacts In Bulk requires a real contact id on every entry. Unlike the single-contact nodes it does not accept an email address in place of an id, because the API documents no address addressing there and the connector will not invent it. Look the ids up first with EmailOctopus: List Contacts, or use the single-contact nodes where you only hold addresses. Note also that this endpoint returns PARTIAL SUCCESS by design: it answers HTTP 200 with successes and errors in separate parts of the response, so a workflow that only checks the status code will treat a half-failed batch as a clean run. Read the errors part explicitly.
A workflow starts failing after a tag or field was renamed
EmailOctopus: Rename Tag and EmailOctopus: Update Field move everything inside EmailOctopus with them: every contact carrying the tag, and every automation triggered by it. What does not move is anything outside EmailOctopus that referenced the old name, including other nodes in your own workflows that had the old value typed into them, and any live campaign template merging a renamed field's token. Update those in the same pass. For a field rename specifically, the field's tag is the key that contact values are written under, so a rename changes where new values land.
A run hits HTTP 429, or a large sync slows down
EmailOctopus rate limits with a token bucket: a bucket of up to 100 tokens replenished at 10 per second, one token per request, which is a steady 10 requests a second or a burst of 100. Over that the API answers HTTP 429, and the vendor's help centre adds that the connection is blocked for up to a minute, which is why a run that trips the limit stalls rather than failing instantly. The structural fix is to send fewer, larger requests: use EmailOctopus: Update Contacts In Bulk instead of a loop of single updates, and use a paged list read rather than a lookup per row. Where a workflow genuinely has to iterate, put a delay between iterations rather than running them as fast as the canvas will allow.

EmailOctopus is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products