The EmailOctopus connector lets your AI agent act in each user's EmailOctopus account. Each user connects their own EmailOctopus access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 25 tools.
- Tools
- 25
- What they doRead · write · destructive
- 10 · 11 · 410 read11 write4 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the EmailOctopus connection
In AgentKit > Connections, create an EmailOctopus connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'emailoctopus'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize EmailOctopus:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'emailoctopus_campaigns_list',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "emailoctopus"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize EmailOctopus:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="emailoctopus_campaigns_list",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their EmailOctopus credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolemailoctopus_campaign_getGet one EmailOctopus campaign by ID.Read-onlyGet Campaign
Get one EmailOctopus campaign by ID. Returns its name, subject, from address, content, status, target lists and sent_at. Use Get Campaign Summary Report for its results.
Inputs
campaign_idstringrequired- ID of the campaign. Find it with List Campaigns. Example: 9a8b7c6d-5e4f-11ef-9a1b-2c3d4e5f6a7b.
emailoctopus_campaign_report_contacts_listList the contacts in one result group of a sent EmailOctopus campaign, such as those who opened or bounced.Read-onlyGet Campaign Contact Report
List the contacts in one result group of a sent EmailOctopus campaign, such as those who opened or bounced. Returns a page of contacts with id, email_address and the event time. The status input picks the group.
Inputs
campaign_idstringrequired- ID of the campaign. Find it with List Campaigns. Example: 9a8b7c6d-5e4f-11ef-9a1b-2c3d4e5f6a7b.
statusstringrequired- Which contacts to return: bounced, clicked, complained, opened, sent, unsubscribed or not-opened. Example: opened.one of
bouncedclickedcomplainedopenedsentunsubscribednot-openednot-clicked limitinteger- Maximum number of results per page, up to 100. Example: 100.
starting_afterstring- Cursor for the next page: the value of paging.next.starting_after from the previous response. Example: WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0.
emailoctopus_campaign_report_links_getGet the per-link click results of a sent EmailOctopus campaign.Read-onlyGet Campaign Links Report
Get the per-link click results of a sent EmailOctopus campaign. Returns each link URL with its total and unique clicks. Use Get Campaign Summary Report for overall totals.
Inputs
campaign_idstringrequired- ID of the campaign. Find it with List Campaigns. Example: 9a8b7c6d-5e4f-11ef-9a1b-2c3d4e5f6a7b.
emailoctopus_campaign_report_summary_getGet the summary results of a sent EmailOctopus campaign.Read-onlyGet Campaign Summary Report
Get the summary results of a sent EmailOctopus campaign. Returns totals and unique counts for sent, opened, clicked, bounced, complained and unsubscribed. Use Get Campaign Contact Report for the contacts behind a number.
Inputs
campaign_idstringrequired- ID of the campaign. Find it with List Campaigns. Example: 9a8b7c6d-5e4f-11ef-9a1b-2c3d4e5f6a7b.
emailoctopus_campaigns_listList the email campaigns in the EmailOctopus account, a page at a time.Read-onlyList Campaigns
List the email campaigns in the EmailOctopus account, a page at a time. Returns each campaign's id, name, subject, status, sent_at and lists, plus a paging cursor. Use Get Campaign for content, or the report tools for results.
Inputs
limitinteger- Maximum number of results per page, up to 100. Example: 100.
starting_afterstring- Cursor for the next page: the value of paging.next.starting_after from the previous response. Example: WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0.
emailoctopus_contact_getGet one contact on an EmailOctopus list, by contact ID or by the MD5 hash of the lowercased email address.Read-onlyGet Contact
Get one contact on an EmailOctopus list, by contact ID or by the MD5 hash of the lowercased email address. Returns the contact's email_address, fields, tags, status and dates. Use List Contacts to browse a list.
Inputs
contact_idstringrequired- ID of the contact, or the MD5 hash of the contact's lowercased email address. Find it with List Contacts. Example: 6f1c2a8b-5d3e-11ef-8a1b-2c3d4e5f6a7b.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
emailoctopus_contacts_listList contacts on an EmailOctopus list, filtered by tag, status or created/updated dates.Read-onlyList Contacts
List contacts on an EmailOctopus list, filtered by tag, status or created/updated dates. Returns each contact's id, email_address, fields, tags, status and dates, plus a paging cursor. Use Get Contact for one contact by ID or email hash.
Inputs
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
created_at_gtestring- Filter by creation date - greater than or equal to. ISO 8601 date format. Example: 2026-01-01T00:00:00Z.
created_at_ltestring- Filter by creation date - less than or equal to. ISO 8601 date format. Example: 2026-01-31T23:59:59Z.
last_updated_at_gtestring- Filter by update date - greater than or equal to. ISO 8601 date format. Example: 2026-01-01T00:00:00Z.
last_updated_at_ltestring- Filter by update date - less than or equal to. ISO 8601 date format. Example: 2026-01-31T23:59:59Z.
limitinteger- Maximum number of results per page, up to 100. Example: 100.
starting_afterstring- Cursor for the next page: the value of paging.next.starting_after from the previous response. Example: WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0.
statusstring- The status of the contact. Example: subscribed.one of
subscribedunsubscribedpending tagstring- The tag associated with the contact. Example: vip.
emailoctopus_list_getGet one EmailOctopus list by ID.Read-onlyGet List
Get one EmailOctopus list by ID. Returns its name, custom fields (with their tags and types), tags and subscriber counts. Use this to learn a list's field tags before creating contacts.
Inputs
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
emailoctopus_lists_listList the mailing lists in the EmailOctopus account, a page at a time.Read-onlyList Lists
List the mailing lists in the EmailOctopus account, a page at a time. Returns each list's id, name, fields, tags, contact counts and created_at, plus a paging cursor. Use this to find a list ID. Use Get List for one list.
Inputs
limitinteger- Maximum number of results per page, up to 100. Example: 100.
starting_afterstring- Cursor for the next page: the value of paging.next.starting_after from the previous response. Example: WyIyMDI0LTEyLTA3VDE1OjAzOjAxKzAwOjAwIiwiNDYzN2RmYTAtYjZmMC0xMWVmLWFjZDYtZjU5YjA4MDFlMjBkIl0.
emailoctopus_automation_contact_startStart an EmailOctopus automation for one contact, as if its trigger had fired.WriteStart Automation For Contact
Start an EmailOctopus automation for one contact, as if its trigger had fired. Returns an empty success response; 409 if the contact is already in it. The automation must use the "started via API" trigger and the contact must be on the automation's list.
Inputs
automation_idstringrequired- ID of the automation, from its URL in the EmailOctopus dashboard. Example: 1b2c3d4e-5f6a-11ef-8b7c-9d0e1f2a3b4c.
contact_idstringrequired- ID of the contact to start the automation for, from List Contacts. Example: 6f1c2a8b-5d3e-11ef-8a1b-2c3d4e5f6a7b.
emailoctopus_contact_createAdd a new contact to an EmailOctopus list.WriteCreate Contact
Add a new contact to an EmailOctopus list. Returns the new contact with its id; fails with 409 if the email is already on the list. Use Create Or Update Contact to upsert by email instead.
Inputs
email_addressstringrequired- The email address of the contact. Example: otto@example.com.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
fieldsobject- Custom field values as an object keyed by each field's tag (see List Fields in Get List), e.g. FirstName. Values are text, numbers, dates (YYYY-MM-DD) or choices. Example: {"FirstName": "Otto"}.
statusstring- Subscription status. pending sends a double opt-in confirmation email if the list has one. Example: subscribed.one of
pendingsubscribedunsubscribed tagsarray- Tag names to apply to the new contact. Example: ["vip"].
emailoctopus_contact_updateUpdate a contact's email address, field values, tags or status on an EmailOctopus list.WriteUpdate Contact
Update a contact's email address, field values, tags or status on an EmailOctopus list. Returns the updated contact. Only the fields you send change; tags are added or removed per key.
- Idempotent
Inputs
contact_idstringrequired- ID of the contact, or the MD5 hash of the contact's lowercased email address. Find it with List Contacts. Example: 6f1c2a8b-5d3e-11ef-8a1b-2c3d4e5f6a7b.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
email_addressstring- The email address of the contact. Example: otto@example.com.
fieldsobject- Custom field values as an object keyed by each field's tag (see List Fields in Get List), e.g. FirstName. Values are text, numbers, dates (YYYY-MM-DD) or choices. Example: {"FirstName": "Otto"}.
statusstring- The status of the contact. Example: unsubscribed.one of
pendingsubscribedunsubscribed tagsobject- Tags to add or remove: an object whose keys are tag names and whose values are true to add the tag or false to remove it. Tags not mentioned are left unchanged. Example: {"vip": true, "trial": false}.
emailoctopus_contact_upsertCreate a contact on an EmailOctopus list, or update it if the email address is already there.WriteCreate Or Update Contact
Create a contact on an EmailOctopus list, or update it if the email address is already there. Returns the created or updated contact. Use Create Contact to fail on duplicates instead.
- Idempotent
Inputs
email_addressstringrequired- The email address of the contact. Example: otto@example.com.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
fieldsobject- Custom field values as an object keyed by each field's tag (see List Fields in Get List), e.g. FirstName. Values are text, numbers, dates (YYYY-MM-DD) or choices. Example: {"FirstName": "Otto"}.
statusstring- The status of the contact. Example: subscribed.one of
pendingsubscribedunsubscribed tagsobject- Tags to add or remove: an object whose keys are tag names and whose values are true to add the tag or false to remove it. Tags not mentioned are left unchanged. Example: {"vip": true, "trial": false}.
emailoctopus_contacts_batch_updateUpdate up to 100 contacts on an EmailOctopus list in one call.WriteUpdate Contacts In Bulk
Update up to 100 contacts on an EmailOctopus list in one call. Returns the per-contact results, including any errors. Each item needs the contact id plus the email_address, fields, tags or status to change.
- Idempotent
Inputs
contactsarrayrequired- Contacts to update, up to 100. Each item has the contact id (or MD5 hash of the lowercased email) and any of email_address, fields (object keyed by field tag), tags (object of tag name to true/false) and status. Example: [{"id": "6f1c2a8b-5d3e-11ef-8a1b-2c3d4e5f6a7b", "tags": {"vip": true}, "status": "subscribed"}].
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
emailoctopus_list_createCreate a new mailing list in EmailOctopus.WriteCreate List
Create a new mailing list in EmailOctopus. Returns the new list with its id. Add custom fields with Create Field and contacts with Create Contact.
Inputs
namestringrequired- The name of the list. Example: Newsletter subscribers.
emailoctopus_list_field_createAdd a custom field to an EmailOctopus list.WriteCreate Field
Add a custom field to an EmailOctopus list. Returns the new field with its label, tag, type and fallback. Choice fields need choices. Use the field's tag as the key in a contact's fields.
Inputs
labelstringrequired- A human readable label for the field. Example: What is your hometown?.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
tagstringrequired- The ID used to reference the field in your emails. Example: Hometown.
typestringrequired- Field type: text, number, date, choice_single (one of the choices) or choice_multiple (several choices). Example: text.one of
textnumberdatechoice_singlechoice_multiple choicesarray- The allowed values. Required when type is choice_single or choice_multiple; omit otherwise. Example: ["One", "Two"].
fallbackstring- A default value for the field, used in campaigns when there is no other value available. Example: Unknown.
emailoctopus_list_field_updateUpdate a custom field's label, tag or fallback on an EmailOctopus list.WriteUpdate Field
Update a custom field's label, tag or fallback on an EmailOctopus list. Returns the updated field. The field's type cannot change; send its current type.
- Idempotent
Inputs
field_tagstringrequired- The current tag of the field to update, as listed in Get List. Example: Hometown.
labelstringrequired- A human readable label for the field. Example: Home town.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
tagstringrequired- The field's tag after the update; send the current tag to keep it. Example: HomeTown.
typestringrequired- The type of the field. Example: text.one of
textnumberdate fallbackstring- A default value for the field, used in campaigns when there is no other value available. Example: Unknown.
emailoctopus_list_tag_createCreate a tag on an EmailOctopus list.WriteCreate Tag
Create a tag on an EmailOctopus list. Returns the new tag. Apply it to contacts with Update Contact.
Inputs
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
tagstringrequired- Name of the tag to create. Example: vip.
emailoctopus_list_tag_updateRename a tag on an EmailOctopus list; contacts keep it under the new name.WriteRename Tag
Rename a tag on an EmailOctopus list; contacts keep it under the new name. Returns the updated tag. Use List Tags to find the current name.
- Idempotent
Inputs
current_tagstringrequired- Current name of the tag to rename. Example: vip.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
new_tagstringrequired- New name for the tag. Example: premium.
emailoctopus_list_updateRename an EmailOctopus list.WriteRename List
Rename an EmailOctopus list. Returns the updated list. Use List Lists to find the list ID.
- Idempotent
Inputs
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
namestringrequired- The name of the list. Example: Monthly newsletter.
emailoctopus_contact_deleteDelete a contact from an EmailOctopus list.DestructiveDelete Contact
Delete a contact from an EmailOctopus list. Returns an empty success response. To stop emails but keep the record, use Update Contact with status unsubscribed.
- Idempotent
Inputs
contact_idstringrequired- ID of the contact, or the MD5 hash of the contact's lowercased email address. Find it with List Contacts. Example: 6f1c2a8b-5d3e-11ef-8a1b-2c3d4e5f6a7b.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
emailoctopus_list_deleteDelete an EmailOctopus list and all its contacts.DestructiveDelete List
Delete an EmailOctopus list and all its contacts. Returns an empty success response. This cannot be undone.
- Idempotent
Inputs
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
emailoctopus_list_field_deleteDelete a custom field from an EmailOctopus list, with its values on every contact.DestructiveDelete Field
Delete a custom field from an EmailOctopus list, with its values on every contact. Returns an empty success response. Use Get List to find the field's tag.
- Idempotent
Inputs
field_tagstringrequired- The tag of the field to delete, as listed in Get List. Example: Hometown.
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
emailoctopus_list_tag_deleteDelete a tag from an EmailOctopus list and remove it from every contact.DestructiveDelete Tag
Delete a tag from an EmailOctopus list and remove it from every contact. Returns an empty success response. Use List Tags to find the name.
- Idempotent
Inputs
list_idstringrequired- ID of the EmailOctopus list. Find it with List Lists. Example: 4637dfa0-b6f0-11ef-acd6-f59b0801e20d.
tagstringrequired- Name of the tag to delete. Example: vip.
No tools match.