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.
Connect EmailOctopus to Mattering
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
A palette search for a send or schedule node finds nothing
A contact you know exists returns 404 when looked up by email address
A contact list looks short, or unsubscribed contacts are missing
A report node returns nothing for a campaign you definitely sent
Creating a field or a tag fails with an out-of-limits error
Creating a contact fails with an already-exists error on a step that is being retried
A bulk update rejects entries that the single update node accepts
A workflow starts failing after a tag or field was renamed
A run hits HTTP 429, or a large sync slows down
Related
The EmailOctopus MCP
What connecting EmailOctopus unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.