Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to SparkPost

Scalekit connector
Open markdown

The SparkPost connector lets your AI agent act in each user's SparkPost account. Each user connects their own SparkPost API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 60 tools.

Tools
60
What they doRead · write · destructive
31 · 20 · 931 read20 write9 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 SparkPost connection

    In AgentKit > Connections, create a SparkPost 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 = 'sparkpost'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize SparkPost:', 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: 'sparkpost_account_get',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their SparkPost 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
  • sparkpost_account_getRetrieve the SparkPost account's details, plan and options.Read-only

    Get Account

    Retrieve the SparkPost account's details, plan and options. Returns results with customer_id, company_name, status, subscription, usage limits and options.

    Inputs

    includestring
    Extra account details to include. The only valid value is usage. Example: usageone of usage
  • sparkpost_content_previewRender inline email content with substitution data without saving or sending it.Read-only

    Preview Inline Content

    Render inline email content with substitution data without saving or sending it. Returns results with the expanded from, subject, html, text and headers. Use this to test template-language content. Use sparkpost_template_preview for a stored template.

    Inputs

    contentobjectrequired
    Content to render: from, subject, html and/or text, plus optional reply_to and headers. Example: {"from": "orders@mail.example.com", "subject": "Hi {{first_name}}", "html": "<p>Order {{order_id}}</p>"}
    substitution_dataobject
    Data passed to the template engine. Example: {"first_name": "Jane", "order_id": "A1001"}
  • sparkpost_event_fields_getList the fields that message events can contain, with descriptions per event type.Read-only

    Get Event Field Documentation

    List the fields that message events can contain, with descriptions per event type. Returns results, an object keyed by event type with each field's description and sample value. Use this to interpret sparkpost_message_events_search results.

    Inputs

    This tool takes no inputs.

  • sparkpost_inbound_domains_listList the domains SparkPost receives inbound email for.Read-only

    List Inbound Domains

    List the domains SparkPost receives inbound email for. Returns results, an array of objects with domain.

    Inputs

    This tool takes no inputs.

  • sparkpost_metrics_breakdown_getGet deliverability and engagement metrics grouped by one dimension, such as recipient domain, campaign, template, sending domain or mailbox provider.Read-only

    Get Metrics Breakdown

    Get deliverability and engagement metrics grouped by one dimension, such as recipient domain, campaign, template, sending domain or mailbox provider. Returns results, an array of objects with the group key (for example domain or campaign_id) plus each requested metric.

    Inputs

    fromstringrequired
    Start of the time window, in YYYY-MM-DDTHH:MM format (UTC unless timezone is set) Example: 2026-11-01T00:00
    group_bystringrequired
    Dimension to group by. Example: campaignone of domainsending-domaincampaigntemplatesubaccountsending-ipip-poolmailbox-providermailbox-provider-regionsubject-campaignwatched-domain
    metricsstringrequired
    Comma-separated metrics to return, such as count_targeted, count_sent, count_delivered, count_bounce, count_hard_bounce, count_soft_bounce, count_rejected, count_spam_complaint, count_unique_confirmed_opened, count_unique_clicked, count_delayed or total_msg_volume. See the SparkPost Metrics API for the full list. Example: count_targeted,count_delivered,count_bounce,count_unique_clicked
    campaignsstring
    Comma-separated campaign IDs to include. Example: black-friday
    domainsstring
    Comma-separated recipient domains to include. Example: gmail.com,yahoo.com
    ip_poolsstring
    Comma-separated IP pool IDs to include (dedicated IP accounts) Example: default
    limitinteger
    Maximum number of groups to return. Example: 10
    order_bystring
    Metric to sort by, descending. Example: count_delivered
    precisionstring
    Precision of the time-window bounds. Every value works for windows up to 24 hours; hour also works up to 31 days; day returns data in UTC regardless of timezone. Defaults to 1min. Example: hourone of 1min5min15minhourday
    sending_domainsstring
    Comma-separated sending domains to include. Example: mail.example.com
    sending_ipsstring
    Comma-separated sending IPs to include (dedicated IP accounts) Example: 192.0.2.10
    subaccountsstring
    Comma-separated subaccount IDs to include. Example: 101,102
    templatesstring
    Comma-separated template IDs to include. Example: welcome-email
    timezonestring
    IANA time zone for the window and buckets. Defaults to UTC. Example: America/New_York
    tostring
    End of the time window, in YYYY-MM-DDTHH:MM format. Defaults to now. Example: 2026-11-13T00:00
  • sparkpost_metrics_engagement_details_getGet click counts per tracked link (link name or URL).Read-only

    Get Link Engagement Details

    Get click counts per tracked link (link name or URL). Returns results, an array with link_name (or url) and count_clicked, count_raw_clicked and count_unique_clicked.

    Inputs

    fromstringrequired
    Start of the window, YYYY-MM-DDTHH:MM. Example: 2026-11-01T00:00
    campaignsstring
    Comma-separated campaign IDs. Example: fall-sale-2026
    limitinteger
    Maximum number of links to return. Example: 20
    metricsstring
    Comma-separated click metrics: count_clicked, count_raw_clicked, count_unique_clicked. Example: count_clicked,count_unique_clicked
    sending_domainsstring
    Comma-separated sending domains. Example: mail.example.com
    subaccountsstring
    Comma-separated subaccount IDs. Example: 101
    templatesstring
    Comma-separated template IDs. Example: newsletter
    timezonestring
    IANA time zone. Defaults to UTC. Example: UTC
    tostring
    End of the window, YYYY-MM-DDTHH:MM. Defaults to now. Example: 2026-11-13T00:00
  • sparkpost_metrics_reasons_getGet the reasons behind bounces, rejections or delays with counts, or bounce counts by classification.Read-only

    Get Bounce, Rejection or Delay Reasons

    Get the reasons behind bounces, rejections or delays with counts, or bounce counts by classification. Returns results, an array of objects with reason (or classification_id and bounce_class_name) and counts such as count_bounce, count_rejected or count_delayed.

    Inputs

    fromstringrequired
    Start of the time window, in YYYY-MM-DDTHH:MM format (UTC unless timezone is set) Example: 2026-11-01T00:00
    reason_typestringrequired
    Which breakdown to return. Example: bounce-reasonone of bounce-reasonbounce-classificationrejection-reasondelay-reason
    campaignsstring
    Comma-separated campaign IDs to include. Example: black-friday
    domainsstring
    Comma-separated recipient domains to include. Example: gmail.com,yahoo.com
    ip_poolsstring
    Comma-separated IP pool IDs to include (dedicated IP accounts) Example: default
    limitinteger
    Maximum number of reasons to return. Example: 20
    metricsstring
    Comma-separated metrics to return, such as count_targeted, count_sent, count_delivered, count_bounce, count_hard_bounce, count_soft_bounce, count_rejected, count_spam_complaint, count_unique_confirmed_opened, count_unique_clicked, count_delayed or total_msg_volume. See the SparkPost Metrics API for the full list. Example: count_targeted,count_delivered,count_bounce,count_unique_clicked
    sending_domainsstring
    Comma-separated sending domains to include. Example: mail.example.com
    sending_ipsstring
    Comma-separated sending IPs to include (dedicated IP accounts) Example: 192.0.2.10
    subaccountsstring
    Comma-separated subaccount IDs to include. Example: 101,102
    templatesstring
    Comma-separated template IDs to include. Example: welcome-email
    timezonestring
    IANA time zone for the window and buckets. Defaults to UTC. Example: America/New_York
    tostring
    End of the time window, in YYYY-MM-DDTHH:MM format. Defaults to now. Example: 2026-11-13T00:00