Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to EmailOctopus

Scalekit connector
Open markdown

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

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. 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>
  3. Create the EmailOctopus connection

    In AgentKit > Connections, create an EmailOctopus connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. 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.actions
    const connector = 'emailoctopus'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { 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 call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'emailoctopus_campaigns_list',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each 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 to execute_tool
Try in PlaygroundRequest a tool
  • emailoctopus_campaign_getGet one EmailOctopus campaign by ID.Read-only

    Get 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-only

    Get 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_summary_getGet the summary results of a sent EmailOctopus campaign.Read-only

    Get 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-only

    List 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-only

    Get 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-only

    List 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-only

    Get 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.