An EmailOctopus MCP for list sync and campaign reporting
32 nodes on the EmailOctopus v2 API: contact lists, contacts with an email-keyed upsert, custom fields, tags, campaigns and every campaign report, including eight separately named segments such as who did not open and who did not click. One thing to know before you plan anything: EmailOctopus does not support sending over its API, so this connector keeps your lists in sync and reads back what the campaigns you sent by hand actually did.
What the EmailOctopus MCP connector does
The EmailOctopus connector for Mattering Automations is 32 nodes on the EmailOctopus v2 API at api.emailoctopus.com. Seventeen of them read and fifteen act. Contact lists cover create, rename, read and delete. Contacts cover list, get, create, an email-keyed create-or-update, update, bulk update and delete. Custom fields and tags each get create, update or rename, and delete. Campaigns are read only, with a lister, a single-campaign read, a headline summary report, a per-link click report, and eight nodes covering the eight campaign report segments.
Every capability is a node on the Automations canvas, and every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. So an agent can pull the people who ignored last week's campaign with EmailOctopus: Campaign Not Opened By, hand you the list, and the same node can sit on a canvas running to a schedule with nobody present.
Start with the ceiling, because it is the single most important fact about this integration and it is better read here than discovered after you have built a workflow. EmailOctopus does not support sending email over its API. In the vendor's own words, all emails sent through EmailOctopus need to be created directly in the Dashboard. The API corroborates that by omission: across its 25 documented operations there is no campaign create, no campaign update, no campaign send, no test send and no scheduling call at all, so a send-campaign node is not something this connector chose to leave out, it is something the API cannot do. What the connector is for is keeping a list in sync from your own systems, and reading back what the campaigns you sent by hand actually did.
There is one exception and it is deliberately loud. EmailOctopus: Start Automation For Contact queues a single contact into an automation you built in the EmailOctopus dashboard, and that automation can send real mail that cannot be recalled. It is the only node in the connector that can cause EmailOctopus to send anything, it is flagged destructive, and its description says so in its opening words. Two constraints go with it: the automation has to be set to the Started via API trigger type or the contact is not accepted, and by default a contact can enter a given automation only once, so a re-run quietly does nothing until you enable repeats in the dashboard.
This connector is v2 only, and that matters more than a version number usually does. EmailOctopus runs a second, older API at emailoctopus.com/api/1.6/ that shares nothing structural with v2: a different host, the key in a query parameter rather than an Authorization header, offset pagination rather than cursors, and a different error envelope. EmailOctopus marks that older version legacy and no longer actively maintained while saying it will keep working as usual, so the distinction does not fade with time. The practical consequence is the setup trap below: a key you already have from an older EmailOctopus integration is likely to be labelled legacy in your account, and a legacy key is rejected by v2 with an ordinary 401 that looks exactly like a wrong key. Mint a new one, which the vendor states is compatible with every version of the API.
The eight report segments are the part of this connector worth showing to somebody. EmailOctopus v2 collapses what reads like eight report endpoints into one path with a required status parameter, which makes the useful questions hard to find and easy to configure wrongly. Here they are 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, so the value cannot be mistyped, and the two negative segments get the plainest names because re-engagement is the reason most people open campaign reports at all.
Contacts can be addressed by email address, not only by id. EmailOctopus keys a contact on the MD5 hash of its lowercased address, and a hash of a mixed-case address returns a clean 404 that is indistinguishable from a contact who genuinely is not there. Addresses arriving from a form, a CRM export or a webhook carry mixed case eventually, so the connector strips, lowercases and hashes for you on EmailOctopus: Get Contact, EmailOctopus: Update Contact, EmailOctopus: Delete Contact and EmailOctopus: Start Automation For Contact. A value that is already an id or an existing digest passes through untouched. EmailOctopus: Update Contacts In Bulk is the exception and it is honest about it: the API requires a real id on every entry there, so the connector does not invent addressing the vendor does not document.
Two operational notes for building. Paging is an opaque forward-only cursor: a response carries paging.next.starting_after, a page holds at most 100 results, and a response arriving with no paging.next at all is the last page, so a loop terminates on absence rather than on a flag turning false. And 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, which allows a steady 10 requests a second or a burst of 100. Over that you get an HTTP 429 and, per the vendor's help centre, a connection blocked for up to a minute. That is the reason EmailOctopus: Update Contacts In Bulk exists: one request that revises many contacts is how a large sync stays inside the budget, rather than a loop of single updates.
Access is honestly free to start with. EmailOctopus describes its Starter plan as free forever and as including all the features it offers, with a published set of limitations: 2,500 contacts stored, 10,000 emails a month, campaign reports kept for 30 days, one user per account, 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. No API restriction appears anywhere in that list, which is why a free account can use this connector properly rather than as a demo. The limit worth designing around is the 30-day report retention: on a free plan a report node asked about an older campaign returns nothing rather than an error.
One connection, three surfaces
- Visual automations. Drag EmailOctopus nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every EmailOctopus node, ready to drop on the canvas
32 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 17
EmailOctopus: Campaign Bounced For
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
Connecting EmailOctopus takes one credential
You create the key on the API keys screen in your EmailOctopus account, at dashboard.emailoctopus.com under the developer settings. The important instruction is to create a NEW key rather than reuse one you already have. EmailOctopus shipped v2 as a new host with a new authentication style, and its documentation states that a key created before the release of v2, labelled legacy, needs replacing and that new API keys are compatible with all versions of the API. A legacy key is rejected by v2 with an ordinary HTTP 401, which is the same response a completely wrong key gives, so there is nothing in the failure to tell you that the key itself is fine and simply too old. Keys are account-wide rather than per list, so one credential reaches every list, campaign and report in the account.
Sign in to EmailOctopus and open the API keys screen in your account's developer settings. If a key there is marked legacy, do not copy it: create a new one alongside it. The old key keeps working for whatever older integration is using the 1.6 API.
Click to add a key, name it something that says where it is used, and copy the value. EmailOctopus shows a new key once, so copy it before leaving the screen. Treat it as account-wide access to your contact data, including every subscriber address on every list, and store it accordingly.
In Mattering Automations, open Connectors, click Add Connector and choose EmailOctopus. Create a new credential and paste the key into the API key field.
Click Test Connection. Mattering calls the lists endpoint, which is the same call EmailOctopus's own authentication documentation tells you to make to confirm a key works. A 401 here means either a wrong key or a legacy key, and the two look identical, so if you are confident the key is right, mint a fresh one before debugging anything else.
All 32 EmailOctopus nodes appear in the canvas palette. Run EmailOctopus: List Contact Lists first: it takes no parameters, proves the credential end to end, and returns the list ids that every other node in the connector needs. The key is stored encrypted in your workspace credential store, so it is held once rather than pasted into each person's config, and revoking it in EmailOctopus ends the connection immediately.
Common uses for the EmailOctopus MCP
Keep a list in sync from the system that owns the customer
The node most sync workflows want is EmailOctopus: Create Or Update Contact, because it is keyed on the email address rather than on an id. Nothing has to be looked up first, a retried step produces the same result as the first attempt instead of an already-exists error, and custom field values ride along in the same call. A signup in your product, a new row in a CRM or a form submission becomes a subscriber with their plan, their signup source and their segment tags already set. Where a batch of people changes at once, EmailOctopus: Update Contacts In Bulk revises many contacts in one request, which is how a large sync stays inside the rate limit.
Re-engagement segments that the API makes hard to ask for
EmailOctopus: Campaign Not Opened By and EmailOctopus: Campaign Not Clicked By answer the two questions people actually reach for campaign reports to answer, and the second is usually the better one: it includes the people who read the email and then did nothing, which is a narrower and more honest re-engagement audience than everyone who did not open. Each row carries the contact id, the email address and when it happened, so the output feeds straight into EmailOctopus: Update Contact to apply a tag, or into EmailOctopus: Start Automation For Contact if you have a nurture sequence waiting in the dashboard. Treat opens as a soft signal while you are here: open tracking is a loaded image, so an image-blocking client suppresses it and a privacy proxy can fire it without a human reading anything.
List hygiene driven by what the last campaign did
EmailOctopus: Campaign Bounced For and EmailOctopus: Campaign Complained About are the two segments worth acting on immediately rather than reporting on. A repeatedly bouncing address costs sender reputation on every future campaign, and a spam complaint is the most damaging outcome in the set. A scheduled workflow can read both after each send, write the addresses back into your own database so the same bad data does not return on the next import, and open a task for a human where a complaint needs a real answer. EmailOctopus: Campaign Unsubscribed From does the same job in the other direction: EmailOctopus has already stopped sending, and this is how your own systems find out.
Campaign results in the place your team already reads
EmailOctopus: Get Campaign Summary Report returns 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. EmailOctopus: Get Campaign Link Report goes one level deeper and lists every tracked link with its total and unique clicks, which answers which call to action worked rather than only how many people clicked something. Pair EmailOctopus: List Campaigns with a schedule and you have a weekly digest into Slack, a Mattering Productivity task or a spreadsheet. Note the shape when you build the digest: opens and clicks are nested objects, so read opened.unique rather than opened.
Provisioning lists, fields and tags from a workflow
Launching a new brand, a new event or a new client usually means the same setup by hand every time. EmailOctopus: Create List opens the list, EmailOctopus: Create Field adds the custom fields campaigns will merge into copy, and EmailOctopus: Create Tag defines the segments. EmailOctopus: Get List reads the whole configuration back, including field definitions and contact counts split into pending, subscribed and unsubscribed, which makes it the natural audit step. Two warnings that the nodes carry themselves: the free plan allows a limited number of fields and tags per list and returns an out-of-limits error past that, and EmailOctopus: Rename Tag moves every contact and every automation with it while anything outside EmailOctopus that references the old name keeps pointing at a name that no longer exists.
An AI assistant that can answer questions about your audience
Because the nodes speak MCP, an assistant such as Claude or ChatGPT can hold a conversation against your real EmailOctopus data: how many subscribed contacts are on this list, what did the last campaign do, who complained. EmailOctopus: Get Contact is the one to know about here, because it accepts an email address directly and answers 404 for a contact who is not there, which makes it a clean does-this-person-exist check without a lookup step first. The sensible split for an assistant is the seventeen read nodes plus the upsert, keeping the four deletes and EmailOctopus: Start Automation For Contact behind a condition or a human approval, since the deletes have no undo and the automation node can send real mail.
Example: A post-campaign follow-up where nothing sends without a person deciding
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Trigger: a schedule fires the morning after your usual send day. This connector ships no trigger nodes, so campaign workflows run on a schedule and read rather than waiting to be pushed to.
EmailOctopus: List Campaigns returns the account's campaigns newest first with their status, so the workflow can pick the most recent one whose status is sent.
EmailOctopus: Get Campaign Summary Report pulls the headline numbers for that campaign in one call, and EmailOctopus: Get Campaign Link Report lists which links were actually clicked.
EmailOctopus: Campaign Not Clicked By returns the re-engagement segment, and EmailOctopus: Campaign Bounced For and EmailOctopus: Campaign Complained About return the two segments that need cleaning up rather than nurturing.
An AI step writes a plain summary of the send and drafts a suggested follow-up angle from which links won. Nothing has been written to EmailOctopus at this point.
EmailOctopus: Update Contact applies a re-engagement tag to the segment, and the bounced and complained addresses are written back into your own database so the next import does not reintroduce them.
A task is created in Mattering Productivity with the numbers and the draft. Sending the follow-up itself happens in the EmailOctopus dashboard, because this API has no send operation, and the only node that can cause mail to go out is EmailOctopus: Start Automation For Contact, which stays behind that approval.
EmailOctopus MCP questions, answered
Can this send an email campaign for me?
No, and no EmailOctopus integration can, because the API has no send operation. EmailOctopus states plainly that all emails sent through EmailOctopus need to be created directly in the Dashboard, and its API confirms it by omission: there is no campaign create, update, send, test send or schedule call anywhere in the version 2 surface, so campaigns are read only here. The one node that can cause EmailOctopus to send anything is EmailOctopus: Start Automation For Contact, which queues a single contact into an automation you built in the dashboard. That automation has to be set to the Started via API trigger type, the node is flagged destructive, and the mail it causes cannot be recalled. What this connector is genuinely good at is the other half of the job: keeping the list in sync from your own systems, and reading back what the campaigns you sent by hand actually did.
What can this connector actually do in EmailOctopus?
32 nodes: 17 read and 15 act. Reads cover contact lists and a single list's full configuration, contacts with filtering by tag, status and date, tags, campaigns and a single campaign, the campaign summary report, the per-link click report, and the eight campaign report segments for sent, opened, not opened, clicked, not clicked, bounced, complained and unsubscribed. Writes cover creating, renaming and deleting lists, creating a contact, an email-keyed create-or-update, updating a contact, a bulk contact update and deleting a contact, creating, updating and deleting custom fields, creating, renaming and deleting tags, and queueing a contact into a dashboard automation. Not included, because the API has no such operation: anything that sends, schedules or creates a campaign. Also not included: trigger nodes. EmailOctopus does publish webhooks for contact events, but they are configured in its dashboard rather than through the API, so the way to use them is to point one at a webhook trigger on a Mattering automation.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and work with EmailOctopus through them. Matter, the assistant built into the platform, uses the same nodes natively. The same nodes are also steps on the automation canvas, so a workflow an assistant helps you design can then run on a schedule with nobody present. Because EmailOctopus contact data is personal data and four of these nodes delete permanently, the sensible split is to hand an assistant the reads and the upsert and keep the deletes and the automation node behind a condition or an approval step.
Does EmailOctopus publish its own MCP server?
No. There is no first-party EmailOctopus MCP server: the vendor publishes no MCP server in its own documentation or developer pages, and it maintains no public code organisation where one could live. That means the connector on this page is the practical way to put EmailOctopus behind an MCP-capable assistant today, and it brings things a locally configured server does not: the nodes also run on a schedule or a trigger with nobody present, chain with every other connector in one workflow, hold the credential once in a shared workspace credential store rather than in each person's local config, and carry destructive flags on the nodes that delete.
My existing EmailOctopus API key returns 401. What is wrong?
It is almost certainly a legacy key. EmailOctopus runs two live APIs: the older 1.6 API at emailoctopus.com/api/1.6/, which takes the key as a query parameter, and version 2 at api.emailoctopus.com, which takes an Authorization: Bearer header. This connector is version 2 only. Keys created before version 2 shipped are labelled legacy in the account and are rejected by version 2, and the vendor's guidance is to generate a new key, which then works with every version of the API. The reason this is worth calling out is that the failure gives you nothing to go on: a legacy key returns an ordinary 401 that is indistinguishable from a wrong key or a typo, so people re-copy a key that was never mistyped. Mint a new key, paste that, and test again.
Can I look a contact up by email address instead of an id?
Yes, and it works on EmailOctopus: Get Contact, EmailOctopus: Update Contact, EmailOctopus: Delete Contact and EmailOctopus: Start Automation For Contact. EmailOctopus addresses a contact by its id or by the MD5 hash of its lowercased email address, and the lowercasing is the whole difficulty: hashing an address exactly as it arrived returns a clean 404 that reads as a missing contact rather than as a formatting problem, and addresses arriving from forms, CRM exports and webhooks carry mixed case eventually. The connector strips, lowercases and hashes for you, so you can pass a raw address straight from an earlier step. A value that is already an id or an already-computed digest is passed through untouched rather than hashed twice. The one node this does not apply to is EmailOctopus: Update Contacts In Bulk, where the API requires a real id on every entry and documents no address addressing, so the connector does not invent it.
Why are there eight campaign report nodes instead of one?
Because the API's single reports path takes a required status parameter with eight values, and folding that into one node with a status box would have hidden eight genuinely different questions inside one configuration nobody searches for. Nobody types reports into a node palette when what they want is the people who did not open. So the connector ships 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 as eight named nodes over the one path. Each pins its own status internally rather than exposing it as a field, so it cannot be mistyped, and they are generated from one shared definition so they cannot drift apart in paging behaviour or wording.
Does the free EmailOctopus plan include API access?
Yes. EmailOctopus describes its Starter plan as free forever and as including all the features it offers, with a published set of limitations, and no API restriction appears among them. The published limits are 2,500 contacts stored, 10,000 emails a month, campaign reports available for 30 days, one user per account, 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. Those are object counts rather than call counts, and they are generous enough that a free account can build and run something real rather than a demo. The one to plan around is the 30-day report retention, because a report node asked about an older campaign on a free plan returns nothing rather than an error. The nodes that create fields and tags say what happens at their ceiling: the API answers with an out-of-limits error rather than failing quietly. Check EmailOctopus's own pricing page before you design around any specific number.
How does pagination and rate limiting work, and can a workflow trigger on an EmailOctopus event?
Paging first: EmailOctopus version 2 uses an opaque forward-only cursor. A paged response carries paging.next.starting_after and you pass that value back in starting_after for the next page. There is no previous link, no page number, no total and no has-more flag, so a response arriving with no paging.next at all is the last page and a loop has to terminate on absence rather than on a flag turning false. The vendor asks that the cursor not be deconstructed, and a response holds at most 100 results, so the page size parameter is a page size rather than a way to pull a large window in one call. Rate limiting is a token bucket: EmailOctopus documents a bucket of up to 100 tokens replenished at 10 per second with one token per request, which is 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. On triggers: this connector ships no trigger nodes, so EmailOctopus steps here run on a schedule or are started by something else, such as a signup in your own product. If you do want push, EmailOctopus publishes webhooks for contact events such as created, updated, unsubscribed, bounced and complained, configured in its dashboard rather than through the API, and one of those can be pointed at a webhook trigger on a Mattering automation.
Put EmailOctopus to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. EmailOctopus is a product of its respective owner; Mattering is an independent platform.