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"
}