Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

EmailOctopus

Add contacts (subscribers) to mailing lists and read lists and campaigns through the EmailOctopus API.

Base URL: https://emailoctopus.com/api/1.6
Auth: api_key query parameter (GET) or JSON body field (POST)
Docs: https://emailoctopus.com/api-documentation

What it does

Wraps the core EmailOctopus list, contact, and campaign endpoints. Run it from any InTouch job, schedule, trigger, or the AI assistant. No external dependencies — standard-library Python only.

Operations

operation	HTTP	path	required inputs	optional inputs
`list-lists`	GET	`/lists`	—	`limit`
`get-list`	GET	`/lists/{listId}`	`listId`	—
`create-contact`	POST	`/lists/{listId}/contacts`	`listId`, `email`	`fields`, `tags`, `status`
`list-campaigns`	GET	`/campaigns`	—	`limit`

Inputs

Input	Required	Description
`apiKey`	Yes	EmailOctopus API key
`operation`	Yes	One of the operations above
`listId`	Conditional	List UUID — required for `get-list` and `create-contact`
`email`	Conditional	Contact email address — required for `create-contact`
`fields`	No	JSON object of field values keyed by field tag, e.g. `{"FirstName":"Jane","LastName":"Doe"}`
`tags`	No	JSON array of tag strings, e.g. `["vip","newsletter"]`
`status`	No	`SUBSCRIBED`, `UNSUBSCRIBED`, or `PENDING` (defaults to list setting)
`limit`	No	Records per page for list operations, 1–100 (default 100)

Outputs

Output	Description
`result`	EmailOctopus API response as a JSON string
`status`	HTTP status code string (`200`, `201`, `400`, `404`, etc.)

Non-2xx responses are returned as data (status + error body in result), not step failures. Only a network-level error (DNS, timeout, refused) fails the step.

API key setup

Sign in to EmailOctopus.
Go to Account Settings → Integrations & API.
Create or copy an API key.
Pass it as apiKey.

Examples

List all mailing lists:

{ "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "operation": "list-lists" }

Get a single list:

{
  "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "operation": "get-list",
  "listId": "00000000-0000-0000-0000-000000000000"
}

Add a contact to a list:

{
  "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "operation": "create-contact",
  "listId": "00000000-0000-0000-0000-000000000000",
  "email": "[email protected]",
  "fields": "{\"FirstName\":\"Jane\",\"LastName\":\"Doe\"}",
  "tags": "[\"vip\",\"newsletter\"]",
  "status": "SUBSCRIBED"
}

List campaigns:

{
  "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "operation": "list-campaigns",
  "limit": "25"
}

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.

error
result
status

Input Properties

Every property this tool accepts, from its own tool.iml.

Property	Type	Required	Default	Description
`apiKey`	string	yes	—	DEPRECATED — bind an API Key credential to the task with `credentialName` instead. A key pasted here is stored in the workflow definition in clear and appears in every export of it. Still honoured for workflows built before the change.
`operation`	string	yes	—	One of: list-lists, get-list, create-contact, list-campaigns
`listId`	string	no	—	The UUID of the mailing list. Required for get-list and create-contact.
`email`	string	no	—	Contact email address. Required for create-contact (sent as email_address).
`fields`	string	no	—	Optional JSON object of contact field values keyed by field tag, e.g. {"FirstName":"Jane","LastName":"Doe"}. Used with create-contact.
`tags`	string	no	—	Optional JSON array of tag strings for the contact, e.g. ["vip","newsletter"]. Used with create-contact.
`status`	string	no	—	Contact status for create-contact: SUBSCRIBED, UNSUBSCRIBED, or PENDING. Leave empty to use the list default.
`limit`	string	no	`100`	Max records per page for list-lists and list-campaigns (1–100, default 100).