> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to SparkPost

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.

**Authentication:** API Key
**Categories:** Communication, Marketing
**Tools:** 60: 31 read, 20 write, 9 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=SPARKPOST)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".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](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   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)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_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.actions

   connection_name = "sparkpost"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize SparkPost:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="sparkpost_account_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their SparkPost credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'sparkpost_account_get',
  toolInput: {},
  connector: 'sparkpost',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="sparkpost_account_get",
    tool_input={},
    connection_name="sparkpost",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `sparkpost_account_get`

Get Account · Read-only

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

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `include` (`string`, optional): Extra account details to include. The only valid value is usage. Example: usage. One of: `usage`.

Example input: `{}`

### `sparkpost_content_preview`

Preview Inline Content · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `content` (`object`, required): 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": "Order {{order_id}}
"}
- `substitution_data` (`object`, optional): Data passed to the template engine. Example: {"first_name": "Jane", "order_id": "A1001"}

Example input: `{"content":{}}`

### `sparkpost_event_fields_get`

Get Event Field Documentation · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `sparkpost_inbound_domains_list`

List Inbound Domains · Read-only

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

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `sparkpost_message_events_search`

Search Message Events · Read-only

Search per-message events (injection, delivery, bounce, open, click, spam complaint and more) from the last 10 days.
Returns results, an array of event objects (type, timestamp, rcpt_to, message_id, transmission_id, subject, reason and more), plus total_count and links.next for the next cursor.
Use this to trace what happened to specific messages or recipients. Use sparkpost_metrics_summary_get for aggregate counts.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bounce_classes` (`string`, optional): Comma-separated bounce classification codes. Example: 10,30
- `campaigns` (`string`, optional): Comma-separated campaign IDs. Example: fall-sale-2026
- `cursor` (`string`, optional): Paging cursor from links.next of the previous response. Defaults to initial. Example: WycyMDE4LTExLTA1VDIyOjQ1OjM5LjAwMFonLCAnc3BjLTM4MTQ1MjY3MjMyNTA2NTEwJ10=
- `event_ids` (`string`, optional): Comma-separated event IDs. Example: 92356927693813856
- `events` (`string`, optional): Comma-separated event types, such as delivery, bounce, injection, delay, open, click, spam_complaint, policy_rejection, list_unsubscribe. Defaults to all. Example: bounce,delivery
- `from` (`string`, optional): Start time (inclusive), YYYY-MM-DDTHH:MM:ssZ in UTC. Defaults to 24 hours ago. Example: 2026-11-12T00:00:00Z
- `from_addresses` (`string`, optional): Comma-separated friendly-from addresses. Example: orders@mail.example.com
- `messages` (`string`, optional): Comma-separated message IDs. Example: 000443ee14578172be22
- `per_page` (`integer`, optional): Results per page, 1 to 10,000. Defaults to 1000. Example: 100
- `reasons` (`string`, optional): Comma-separated bounce, failure or rejection reason keywords. Example: mailbox full
- `recipient_domains` (`string`, optional): Comma-separated recipient domains. Example: gmail.com
- `recipients` (`string`, optional): Comma-separated recipient addresses. Example: jane@example.com
- `sending_domains` (`string`, optional): Comma-separated sending domains. Example: mail.example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `subaccounts` (`string`, optional): Comma-separated subaccount IDs. Example: 101
- `subjects` (`string`, optional): Comma-separated subject keywords. Example: shipped
- `templates` (`string`, optional): Comma-separated template IDs. Example: order-shipped
- `to` (`string`, optional): End time (exclusive), YYYY-MM-DDTHH:MM:ssZ in UTC. Defaults to 1 minute ago. Example: 2026-11-13T00:00:00Z
- `transmissions` (`string`, optional): Comma-separated transmission IDs. Example: 11668787484950529

Example input: `{}`

### `sparkpost_metrics_breakdown_get`

Get Metrics Breakdown · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, required): Start of the time window, in YYYY-MM-DDTHH:MM format (UTC unless timezone is set) Example: 2026-11-01T00:00
- `group_by` (`string`, required): Dimension to group by. Example: campaign. One of: `domain`, `sending-domain`, `campaign`, `template`, `subaccount`, `sending-ip`, `ip-pool`, `mailbox-provider`, `mailbox-provider-region`, `subject-campaign`, `watched-domain`.
- `metrics` (`string`, required): 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
- `campaigns` (`string`, optional): Comma-separated campaign IDs to include. Example: black-friday
- `domains` (`string`, optional): Comma-separated recipient domains to include. Example: gmail.com,yahoo.com
- `ip_pools` (`string`, optional): Comma-separated IP pool IDs to include (dedicated IP accounts) Example: default
- `limit` (`integer`, optional): Maximum number of groups to return. Example: 10
- `order_by` (`string`, optional): Metric to sort by, descending. Example: count_delivered
- `precision` (`string`, optional): 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: hour. One of: `1min`, `5min`, `15min`, `hour`, `day`.
- `sending_domains` (`string`, optional): Comma-separated sending domains to include. Example: mail.example.com
- `sending_ips` (`string`, optional): Comma-separated sending IPs to include (dedicated IP accounts) Example: 192.0.2.10
- `subaccounts` (`string`, optional): Comma-separated subaccount IDs to include. Example: 101,102
- `templates` (`string`, optional): Comma-separated template IDs to include. Example: welcome-email
- `timezone` (`string`, optional): IANA time zone for the window and buckets. Defaults to UTC. Example: America/New_York
- `to` (`string`, optional): End of the time window, in YYYY-MM-DDTHH:MM format. Defaults to now. Example: 2026-11-13T00:00

Example input: `{"from":"<from>","group_by":"domain","metrics":"<metrics>"}`

### `sparkpost_metrics_engagement_details_get`

Get Link Engagement Details · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, required): Start of the window, YYYY-MM-DDTHH:MM. Example: 2026-11-01T00:00
- `campaigns` (`string`, optional): Comma-separated campaign IDs. Example: fall-sale-2026
- `limit` (`integer`, optional): Maximum number of links to return. Example: 20
- `metrics` (`string`, optional): Comma-separated click metrics: count_clicked, count_raw_clicked, count_unique_clicked. Example: count_clicked,count_unique_clicked
- `sending_domains` (`string`, optional): Comma-separated sending domains. Example: mail.example.com
- `subaccounts` (`string`, optional): Comma-separated subaccount IDs. Example: 101
- `templates` (`string`, optional): Comma-separated template IDs. Example: newsletter
- `timezone` (`string`, optional): IANA time zone. Defaults to UTC. Example: UTC
- `to` (`string`, optional): End of the window, YYYY-MM-DDTHH:MM. Defaults to now. Example: 2026-11-13T00:00

Example input: `{"from":"<from>"}`

### `sparkpost_metrics_reasons_get`

Get Bounce, Rejection or Delay Reasons · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, required): Start of the time window, in YYYY-MM-DDTHH:MM format (UTC unless timezone is set) Example: 2026-11-01T00:00
- `reason_type` (`string`, required): Which breakdown to return. Example: bounce-reason. One of: `bounce-reason`, `bounce-classification`, `rejection-reason`, `delay-reason`.
- `campaigns` (`string`, optional): Comma-separated campaign IDs to include. Example: black-friday
- `domains` (`string`, optional): Comma-separated recipient domains to include. Example: gmail.com,yahoo.com
- `ip_pools` (`string`, optional): Comma-separated IP pool IDs to include (dedicated IP accounts) Example: default
- `limit` (`integer`, optional): Maximum number of reasons to return. Example: 20
- `metrics` (`string`, optional): 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_domains` (`string`, optional): Comma-separated sending domains to include. Example: mail.example.com
- `sending_ips` (`string`, optional): Comma-separated sending IPs to include (dedicated IP accounts) Example: 192.0.2.10
- `subaccounts` (`string`, optional): Comma-separated subaccount IDs to include. Example: 101,102
- `templates` (`string`, optional): Comma-separated template IDs to include. Example: welcome-email
- `timezone` (`string`, optional): IANA time zone for the window and buckets. Defaults to UTC. Example: America/New_York
- `to` (`string`, optional): End of the time window, in YYYY-MM-DDTHH:MM format. Defaults to now. Example: 2026-11-13T00:00

Example input: `{"from":"<from>","reason_type":"bounce-reason"}`

### `sparkpost_metrics_summary_get`

Get Metrics Summary · Read-only

Get aggregate deliverability and engagement counts (sent, delivered, bounced, opened, clicked and more) over a time window.
Returns results, an array with one object holding the requested metrics.
Use this for totals. Use sparkpost_metrics_time_series_get for trends and sparkpost_metrics_breakdown_get to group by domain, campaign or template.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, required): Start of the time window, in YYYY-MM-DDTHH:MM format (UTC unless timezone is set) Example: 2026-11-01T00:00
- `metrics` (`string`, required): 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
- `campaigns` (`string`, optional): Comma-separated campaign IDs to include. Example: black-friday
- `domains` (`string`, optional): Comma-separated recipient domains to include. Example: gmail.com,yahoo.com
- `ip_pools` (`string`, optional): Comma-separated IP pool IDs to include (dedicated IP accounts) Example: default
- `precision` (`string`, optional): 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: hour. One of: `1min`, `5min`, `15min`, `hour`, `day`.
- `sending_domains` (`string`, optional): Comma-separated sending domains to include. Example: mail.example.com
- `sending_ips` (`string`, optional): Comma-separated sending IPs to include (dedicated IP accounts) Example: 192.0.2.10
- `subaccounts` (`string`, optional): Comma-separated subaccount IDs to include. Example: 101,102
- `templates` (`string`, optional): Comma-separated template IDs to include. Example: welcome-email
- `timezone` (`string`, optional): IANA time zone for the window and buckets. Defaults to UTC. Example: America/New_York
- `to` (`string`, optional): End of the time window, in YYYY-MM-DDTHH:MM format. Defaults to now. Example: 2026-11-13T00:00

Example input: `{"from":"<from>","metrics":"<metrics>"}`

### `sparkpost_metrics_time_series_get`

Get Metrics Time Series · Read-only

Get deliverability and engagement metrics bucketed over time.
Returns results, an array of objects with ts plus each requested metric, one per bucket of the chosen precision.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, required): Start of the time window, in YYYY-MM-DDTHH:MM format (UTC unless timezone is set) Example: 2026-11-01T00:00
- `metrics` (`string`, required): 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
- `campaigns` (`string`, optional): Comma-separated campaign IDs to include. Example: black-friday
- `domains` (`string`, optional): Comma-separated recipient domains to include. Example: gmail.com,yahoo.com
- `ip_pools` (`string`, optional): Comma-separated IP pool IDs to include (dedicated IP accounts) Example: default
- `precision` (`string`, optional): 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: hour. One of: `1min`, `5min`, `15min`, `hour`, `day`.
- `sending_domains` (`string`, optional): Comma-separated sending domains to include. Example: mail.example.com
- `sending_ips` (`string`, optional): Comma-separated sending IPs to include (dedicated IP accounts) Example: 192.0.2.10
- `subaccounts` (`string`, optional): Comma-separated subaccount IDs to include. Example: 101,102
- `templates` (`string`, optional): Comma-separated template IDs to include. Example: welcome-email
- `timezone` (`string`, optional): IANA time zone for the window and buckets. Defaults to UTC. Example: America/New_York
- `to` (`string`, optional): End of the time window, in YYYY-MM-DDTHH:MM format. Defaults to now. Example: 2026-11-13T00:00

Example input: `{"from":"<from>","metrics":"<metrics>"}`

### `sparkpost_metrics_values_list`

List Metrics Filter Values · Read-only

List the values seen in a time window for one metrics dimension, such as the campaigns, templates or recipient domains that sent mail.
Returns results with an array named after the dimension (for example campaigns or domains).
Use this to find filter values for sparkpost_metrics_summary_get and sparkpost_metrics_breakdown_get.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dimension` (`string`, required): Which values to list. Example: campaigns. One of: `campaigns`, `templates`, `domains`, `sending-domains`, `subject-campaigns`, `mailbox-providers`, `mailbox-provider-regions`, `ip-pools`, `sending-ips`.
- `from` (`string`, required): Start of the window, YYYY-MM-DDTHH:MM. Example: 2026-11-01T00:00
- `limit` (`integer`, optional): Maximum number of values to return. Example: 50
- `match` (`string`, optional): Only values containing this text. Example: sale
- `timezone` (`string`, optional): IANA time zone. Defaults to UTC. Example: UTC
- `to` (`string`, optional): End of the window, YYYY-MM-DDTHH:MM. Defaults to now. Example: 2026-11-13T00:00

Example input: `{"dimension":"campaigns","from":"<from>"}`

### `sparkpost_recipient_list_get`

Get Recipient List · Read-only

Retrieve one stored recipient list, optionally with all of its recipients.
Returns results with id, name, description, attributes, total_accepted_recipients and, with show_recipients, the recipients array.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Recipient list ID (case sensitive) Example: newsletter-subscribers
- `show_recipients` (`boolean`, optional): true includes every recipient in the list. Example: true
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"id":"<id>"}`

### `sparkpost_recipient_lists_list`

List Recipient Lists · Read-only

List the stored recipient lists in the account, without their recipients.
Returns results, an array with id, name, description, attributes and total_accepted_recipients.
Use this to find a list ID. Use sparkpost_recipient_list_get with show_recipients to read the recipients.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{}`

### `sparkpost_relay_webhook_get`

Get Relay Webhook · Read-only

Retrieve one relay webhook.
Returns results with name, target, auth_type, match and custom_headers.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Relay webhook ID. Example: 12013026328707075

Example input: `{"id":"<id>"}`

### `sparkpost_relay_webhooks_list`

List Relay Webhooks · Read-only

List relay webhooks, which forward inbound email on an inbound domain to your URL.
Returns results, an array with id, name, target, auth_type and match (protocol, domain).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `sparkpost_sending_domain_get`

Get Sending Domain · Read-only

Retrieve one sending domain with its DNS records and verification status.
Returns results with tracking_domain, status, dkim (public key, selector, headers) and dns (the DKIM and CNAME records to publish).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, required): Sending domain name. Example: mail.example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"domain":"<domain>"}`

### `sparkpost_sending_domains_list`

List Sending Domains · Read-only

List the sending domains in the account with their verification status.
Returns results, an array with domain, tracking_domain, status (ownership_verified, dkim_status, cname_status, mx_status, compliance_status) and shared_with_subaccounts.
Use this to find a verified from domain. Use sparkpost_sending_domain_get for DNS records.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `cname_status` (`string`, optional): Filter by CNAME (bounce) status. Example: valid. One of: `valid`, `invalid`, `unverified`, `pending`.
- `compliance_status` (`string`, optional): Filter by compliance status. Example: valid. One of: `valid`, `blocked`.
- `dkim_status` (`string`, optional): Filter by DKIM status. Example: valid. One of: `valid`, `invalid`, `unverified`, `pending`.
- `is_default_bounce_domain` (`boolean`, optional): Filter by default bounce domain. Example: false
- `mx_status` (`string`, optional): Filter by MX status. Example: valid. One of: `valid`, `invalid`, `unverified`, `pending`.
- `ownership_verified` (`boolean`, optional): Filter by ownership verification. Example: true
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{}`

### `sparkpost_subaccount_get`

Get Subaccount · Read-only

Retrieve one subaccount.
Returns results with id, name, status, compliance_status, ip_pool and options.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Subaccount ID. Example: 101

Example input: `{"id":101}`

### `sparkpost_subaccounts_list`

List Subaccounts · Read-only

List the account's subaccounts.
Returns results, an array with id, name, status, compliance_status and ip_pool.
Use a subaccount id in the subaccount_id input of other tools.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `sparkpost_suppression_get`

Get Suppression · Read-only

Check whether one email address is suppressed and why.
Returns results, an array of the address's entries with type, source, description, list_id, created and updated; 404 when the address is not suppressed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `recipient` (`string`, required): Email address to look up. Example: jane@example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `types` (`string`, optional): Comma-separated types to match: transactional, non_transactional, open_tracking. Example: transactional,non_transactional

Example input: `{"recipient":"<recipient>"}`

### `sparkpost_suppression_summary_get`

Get Suppression Summary · Read-only

Count suppression entries by source.
Returns results with counts per source (for example bounce_rule, spam_complaint, list_unsubscribe, unsubscribe_link, manually_added, compliance) and a total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{}`

### `sparkpost_suppressions_search`

Search Suppressions · Read-only

Search the suppression list (addresses SparkPost will not send to) by date, domain, source, type or description.
Returns results, an array of entries with recipient, type, source, description, list_id, created and updated, plus links and total_count for paging.
Use this to browse or filter. Use sparkpost_suppression_get to check one address.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `cursor` (`string`, optional): Paging cursor. Use initial for the first page, then the cursor from links in the previous response. Overrides page. Example: initial
- `description` (`string`, optional): Text to match in descriptions. Example: hard bounce
- `description_strict` (`boolean`, optional): true matches description exactly. Example: false
- `domain` (`string`, optional): Comma-separated recipient domains to match. Example: example.com
- `from` (`string`, optional): Only entries last updated at or after this ISO 8601 datetime. Example: 2026-10-01T00:00:00Z
- `list_id` (`string`, optional): Only suppressions for this mailing list ID (RFC 2919). An empty value returns only account-level entries. Example: newsletter.example.com
- `page` (`integer`, optional): Page number when paging without a cursor (up to 10,000 results) Example: 1
- `per_page` (`integer`, optional): Results per page, 1 to 10,000. Defaults to 1000. Example: 100
- `sort` (`string`, optional): Sort by updated time. Defaults to desc. Example: desc. One of: `asc`, `desc`.
- `sources` (`string`, optional): Comma-separated sources to match: Spam Complaint, List Unsubscribe, Bounce Rule, Unsubscribe Link, Manually Added, Compliance, Tracking Consent Revoked (case sensitive) Example: Bounce Rule,Spam Complaint
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `to` (`string`, optional): Only entries last updated before this ISO 8601 datetime. Defaults to now. Example: 2026-11-13T00:00:00Z
- `types` (`string`, optional): Comma-separated types to match: transactional, non_transactional, open_tracking. Defaults to the two sending types. Example: transactional,non_transactional

Example input: `{}`

### `sparkpost_template_get`

Get Template · Read-only

Retrieve one stored template, including its content (from, subject, html, text, headers) and options.
Returns results, the template object with id, name, content, options, published, has_draft and has_published.
Use this after sparkpost_templates_list to read or copy a template's content.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Template ID (case sensitive) Example: order-shipped
- `draft` (`boolean`, optional): true returns the draft version, false the published version. Example: false
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"id":"<id>"}`

### `sparkpost_template_preview`

Preview Template · Read-only

Render a stored template with substitution data, without sending anything.
Returns results with the expanded from, subject, html, text and headers.
Use this to check a template's output before sending with sparkpost_transmission_send.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Template ID (case sensitive) Example: order-shipped
- `draft` (`boolean`, optional): true previews the draft version, false the published version. Example: true
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `substitution_data` (`object`, optional): Data passed to the template engine. Example: {"first_name": "Jane", "order_id": "A1001"}

Example input: `{"id":"<id>"}`

### `sparkpost_templates_list`

List Templates · Read-only

List stored email templates in the account.
Returns results, an array of templates with id, name, description, published, has_draft, has_published, last_update_time and last_use.
Use this to find a template ID. Use sparkpost_template_get for a template's content.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `draft` (`boolean`, optional): true returns draft versions, false returns published versions. Leave empty to return the most recently edited version of each. Example: false
- `shared_with_subaccounts` (`boolean`, optional): true returns only templates shared with subaccounts, false only non-shared ones. Example: false
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{}`

### `sparkpost_tracking_domain_get`

Get Tracking Domain · Read-only

Retrieve one tracking domain with its verification status.
Returns results with domain, port, secure, default and status.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, required): Tracking domain name. Example: click.example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"domain":"<domain>"}`

### `sparkpost_tracking_domains_list`

List Tracking Domains · Read-only

List the custom tracking (click and open) domains in the account.
Returns results, an array with domain, port, secure, default and status (verified, cname_status, compliance_status).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `default` (`boolean`, optional): true returns only default tracking domains. Example: true
- `subaccounts` (`string`, optional): Comma-separated subaccount IDs to include (0 is the primary account) Example: 0,101

Example input: `{}`

### `sparkpost_usage_get`

Get Usage · Read-only

Get the account's sending usage against its daily, monthly and sandbox limits.
Returns results with day, month and sandbox objects (used, limit, start, end).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `sparkpost_webhook_batch_status_get`

Get Webhook Batch Status · Read-only

Read the delivery status of recent batches for a webhook (last 24 hours).
Returns results, an array with batch_id, ts, attempts and response_code.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
- `limit` (`integer`, optional): Maximum number of batches to return. Defaults to 1000. Example: 50
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"id":"<id>"}`

### `sparkpost_webhook_get`

Get Webhook · Read-only

Retrieve one event webhook.
Returns results with name, target, events, active, auth_type, custom_headers and delivery timestamps.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `timezone` (`string`, optional): IANA time zone for timestamps. Example: UTC

Example input: `{"id":"<id>"}`

### `sparkpost_webhooks_list`

List Webhooks · Read-only

List the event webhooks configured in the account.
Returns results, an array with id, name, target, events, active, auth_type and last_successful/last_failure times.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `timezone` (`string`, optional): IANA time zone for the returned timestamps. Defaults to UTC. Example: UTC

Example input: `{}`

### `sparkpost_inbound_domain_create`

Create Inbound Domain · Write

Register a domain to receive inbound email through SparkPost (point its MX records at SparkPost).
Returns an empty result. Then route its mail with sparkpost_relay_webhook_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain` (`string`, required): Domain to receive email for. Example: inbound.example.com

Example input: `{"domain":"<domain>"}`

### `sparkpost_recipient_list_create`

Create Recipient List · Write

Create a stored recipient list for use in sparkpost_transmission_send recipient_list_id.
Returns results with id, name, total_accepted_recipients and total_rejected_recipients.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `recipients` (`array`, required): Recipients in the list. Each item has an address (an email string, or an object with email and optional name), plus optional tags, metadata and substitution_data. Example: [{"address": {"email": "jane@example.com", "name": "Jane"}, "substitution_data": {"plan": "pro"}}]
- `attributes` (`object`, optional): Free-form metadata about the list, not used by the API. Example: {"source": "signup-form"}
- `description` (`string`, optional): Description (max 1024 bytes) Example: Opted-in newsletter readers
- `id` (`string`, optional): Unique list ID (max 64 bytes). Generated when empty. Example: newsletter-subscribers
- `name` (`string`, optional): Display name (max 64 bytes). Defaults to the ID. Example: Newsletter subscribers
- `num_rcpt_errors` (`integer`, optional): Maximum number of recipient errors to return. Example: 3
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"recipients":[{"address":{"email":"jane@example.com","name":"Jane"},"substitution_data":{"plan":"pro"}}]}`

### `sparkpost_recipient_list_update`

Update Recipient List · Write

Update a stored recipient list's name, description, attributes or recipients.
Returns results with id, name and, when recipients changed, the accepted and rejected counts.
A recipients array replaces every existing recipient, so send the full list when adding or removing one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Recipient list ID (case sensitive) Example: newsletter-subscribers
- `attributes` (`object`, optional): Replacement metadata object. Example: {"source": "import"}
- `description` (`string`, optional): New description. Example: Opted-in newsletter readers
- `name` (`string`, optional): New display name. Example: Newsletter subscribers
- `num_rcpt_errors` (`integer`, optional): Maximum number of recipient errors to return. Example: 3
- `recipients` (`array`, optional): Replacement recipients (replaces all existing ones). Same item shape as sparkpost_recipient_list_create. Example: [{"address": "jane@example.com"}]
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"id":"<id>"}`

### `sparkpost_recipient_validate`

Validate Email Address · Write

Check whether an email address is deliverable before sending (syntax, domain, mailbox, role and disposable checks).
Returns results with valid, result (valid, neutral, risky, undeliverable or typo), reason, delivery_confidence (0-100), is_role, is_disposable, is_free and did_you_mean.
Each call is a billable Recipient Validation check.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `address` (`string`, required): Email address to validate. Example: jane@example.com

Example input: `{"address":"<address>"}`

### `sparkpost_relay_webhook_create`

Create Relay Webhook · Write

Forward inbound email received on an inbound domain to your URL as JSON.
Returns results with the relay webhook id.
Prerequisite: the domain must exist (sparkpost_inbound_domain_create).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `match` (`object`, required): Which inbound mail to relay: domain (the inbound domain) and protocol (SMTP) Example: {"protocol": "SMTP", "domain": "inbound.example.com"}
- `target` (`string`, required): URL that receives relayed messages (port 80 or 443) Example: https://example.com/inbound
- `auth_request_details` (`object`, optional): OAuth 2.0 client-credentials details for auth_type oauth2. Example: {"url": "https://example.com/oauth/token", "body": {"client_id": "abc", "client_secret": "xyz"}}
- `auth_token` (`string`, optional): Token sent in the X-MessageSystems-Webhook-Token header. Example: 5ebe2294ecd0e0f08eab7690d2a6ee69
- `auth_type` (`string`, optional): Authentication used when posting. Defaults to none. Example: none. One of: `none`, `oauth2`.
- `custom_headers` (`object`, optional): Extra HTTP headers to send. Example: {"X-Source": "sparkpost"}
- `name` (`string`, optional): Relay webhook name. Example: Support inbox

Example input: `{"match":{"protocol":"SMTP","domain":"inbound.example.com"},"target":"<target>"}`

### `sparkpost_relay_webhook_update`

Update Relay Webhook · Write

Change a relay webhook's name, target, match or authentication.
Returns results with the relay webhook id.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Relay webhook ID. Example: 12013026328707075
- `auth_request_details` (`object`, optional): OAuth 2.0 client-credentials details. Example: {"url": "https://example.com/oauth/token", "body": {"client_id": "abc", "client_secret": "xyz"}}
- `auth_token` (`string`, optional): Token sent in the X-MessageSystems-Webhook-Token header. Example: 5ebe2294ecd0e0f08eab7690d2a6ee69
- `auth_type` (`string`, optional): Authentication used when posting. Example: none. One of: `none`, `oauth2`.
- `custom_headers` (`object`, optional): Extra HTTP headers to send. Example: {"X-Source": "sparkpost"}
- `match` (`object`, optional): Which inbound mail to relay: domain and protocol. Example: {"protocol": "SMTP", "domain": "inbound.example.com"}
- `name` (`string`, optional): Relay webhook name. Example: Support inbox
- `target` (`string`, optional): URL that receives relayed messages. Example: https://example.com/inbound

Example input: `{"id":"<id>"}`

### `sparkpost_sending_domain_create`

Create Sending Domain · Write

Add a sending domain to the account. It must be verified within two weeks or it is removed.
Returns results with domain, a message and, when a DKIM key was generated, the dkim object to publish in DNS.
Next, publish the DNS records and call sparkpost_sending_domain_verify.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain` (`string`, required): Domain to send from. Example: mail.example.com
- `dkim` (`object`, optional): Your own DKIM key instead of a generated one: private, public, selector and optional headers. Example: {"private": "MIICXgIBAAKBgQC...", "public": "MIGfMA0GCSqGSIb3...", "selector": "scph0123"}
- `dkim_key_length` (`integer`, optional): DKIM key size in bits when generating. Defaults to 2048; use 1024 if your DNS host cannot store multi-string TXT records. Example: 2048. One of: `1024`, `2048`.
- `generate_dkim` (`boolean`, optional): Generate a DKIM key pair. Defaults to true. Example: true
- `shared_with_subaccounts` (`boolean`, optional): Let subaccounts send from this domain (primary-account domains only) Example: false
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `tracking_domain` (`string`, optional): Tracking domain to associate (must belong to the same subaccount) Example: click.example.com

Example input: `{"domain":"<domain>"}`

### `sparkpost_sending_domain_update`

Update Sending Domain · Write

Change a sending domain's tracking domain, DKIM key, sharing or default bounce domain setting.
Returns results with domain and a message.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, required): Sending domain name. Example: mail.example.com
- `dkim` (`object`, optional): Replacement DKIM configuration (private, public, selector, optional headers); verified before saving. Example: {"private": "MIICXgIBAAKBgQC...", "public": "MIGfMA0GCSqGSIb3...", "selector": "scph0124"}
- `is_default_bounce_domain` (`boolean`, optional): Use as the default bounce domain (needs a valid CNAME or MX status; not on Enterprise) Example: true
- `shared_with_subaccounts` (`boolean`, optional): Let subaccounts send from this domain. Example: true
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `tracking_domain` (`string`, optional): Tracking domain to associate; empty string removes it. Example: click.example.com

Example input: `{"domain":"<domain>"}`

### `sparkpost_sending_domain_verify`

Verify Sending Domain · Write

Check a sending domain's DNS records (DKIM, CNAME) or start or complete mailbox verification.
Returns results with the domain's status flags and, for DNS checks, a dns object with the records and any errors.
Use after publishing the records from sparkpost_sending_domain_create. Mailbox options send a verification email.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain` (`string`, required): Sending domain name. Example: mail.example.com
- `abuse_at_token` (`string`, optional): Token from the abuse@ verification email. Example: rcF4KlKFm5S2dDh4CcJ1xZ
- `abuse_at_verify` (`boolean`, optional): Email a verification link to abuse@domain. Example: false
- `cname_verify` (`boolean`, optional): Check the bounce CNAME record. Example: true
- `dkim_verify` (`boolean`, optional): Check the DKIM TXT record. Example: true
- `postmaster_at_token` (`string`, optional): Token from the postmaster@ verification email. Example: rcF4KlKFm5S2dDh4CcJ1xZ
- `postmaster_at_verify` (`boolean`, optional): Email a verification link to postmaster@domain. Example: false
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `verification_mailbox` (`string`, optional): Local part of the mailbox for verification_mailbox_verify (not postmaster or abuse) Example: admin
- `verification_mailbox_token` (`string`, optional): Token from the mailbox verification email, to complete verification. Example: rcF4KlKFm5S2dDh4CcJ1xZ
- `verification_mailbox_verify` (`boolean`, optional): Email a verification link to verification_mailbox@domain (not on Enterprise) Example: false

Example input: `{"domain":"<domain>"}`

### `sparkpost_suppression_upsert`

Add or Update Suppression · Write

Add one email address to the suppression list, or update its entry, so SparkPost stops sending it that type of email.
Returns results with a success message.
Use sparkpost_suppressions_bulk_upsert for many addresses.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `recipient` (`string`, required): Email address to suppress. Example: jane@example.com
- `type` (`string`, required): Which mail to block: transactional, non_transactional, or open_tracking (stops open tracking only, mail still delivered) Example: non_transactional. One of: `transactional`, `non_transactional`, `open_tracking`.
- `description` (`string`, optional): Reason for the suppression. Example: Unsubscribed by phone
- `list_id` (`string`, optional): Suppress only for this mailing list ID (RFC 2919). Leave empty for account-wide. Not allowed with open_tracking. Example: newsletter.example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"recipient":"<recipient>","type":"transactional"}`

### `sparkpost_suppressions_bulk_upsert`

Bulk Add or Update Suppressions · Write

Add or update up to 10,000 suppression entries in one call.
Returns results with a success message. On a 5xx some entries may already be saved; resubmit the same request.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `recipients` (`array`, required): Entries to add or update. Each item has recipient (email), type (transactional, non_transactional or open_tracking), and optional description and list_id. Example: [{"recipient": "jane@example.com", "type": "non_transactional", "description": "Imported opt-out"}]
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"recipients":[{"recipient":"jane@example.com","type":"non_transactional","description":"Imported opt-out"}]}`

### `sparkpost_template_create`

Create Template · Write

Create a stored email template. New templates are drafts until published with sparkpost_template_update and published=true.
Returns results with the template id.
Use this to save reusable content for sparkpost_transmission_send template_id.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `content` (`object`, required): Template content: from (address string or object with email and name), subject, and html and/or text, plus optional reply_to, headers and amp_html. The template language works in every field. Alternatively a single email_rfc822 string. Example: {"from": {"email": "orders@mail.example.com", "name": "Acme"}, "subject": "Your order {{order_id}} shipped", "html": "Hi {{first_name}}
"}
- `description` (`string`, optional): Description of the template. Example: Sent when an order ships
- `id` (`string`, optional): Unique alphanumeric template ID (max 64 bytes). Generated from name when empty. Set id or name. Example: order-shipped
- `name` (`string`, optional): Display name (does not need to be unique). Set id or name. Example: Order shipped
- `options` (`object`, optional): Template options, overridable per transmission: open_tracking, click_tracking and transactional (booleans) Example: {"open_tracking": true, "click_tracking": true, "transactional": true}
- `shared_with_subaccounts` (`boolean`, optional): Let subaccounts use this template (primary-account templates only) Example: false
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"content":{}}`

### `sparkpost_template_update`

Update or Publish Template · Write

Update a template's draft, overwrite its published version, or publish the current draft.
Returns an empty result on success.
Use published=true alone to publish the draft. A content object replaces the whole existing content, so include every content field.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Template ID (case sensitive) Example: order-shipped
- `content` (`object`, optional): Replacement content: from, subject, html and/or text, plus optional reply_to, headers and amp_html. Replaces all existing content fields. Example: {"from": "orders@mail.example.com", "subject": "Shipped!", "text": "Hi {{first_name}}"}
- `description` (`string`, optional): New description. Example: Sent when an order ships
- `name` (`string`, optional): New display name. Example: Order shipped v2
- `options` (`object`, optional): Template options: open_tracking, click_tracking and transactional. Example: {"click_tracking": false}
- `published` (`boolean`, optional): Set to true (with no other fields) to publish the current draft as the new published version. Example: true
- `shared_with_subaccounts` (`boolean`, optional): Let subaccounts use this template (updates both versions) Example: true
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `update_published` (`boolean`, optional): true overwrites the published version directly; otherwise the draft is updated. Example: false

Example input: `{"id":"<id>"}`

### `sparkpost_tracking_domain_create`

Create Tracking Domain · Write

Add a custom tracking domain that wraps open pixels and links.
Returns results with domain. Next, add the CNAME record and call sparkpost_tracking_domain_verify.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain` (`string`, required): Tracking domain name. Example: click.example.com
- `secure` (`boolean`, optional): Use HTTPS tracking links. Defaults to false. Example: true
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"domain":"<domain>"}`

### `sparkpost_tracking_domain_update`

Update Tracking Domain · Write

Change whether a tracking domain uses HTTPS or is the default.
Returns results with domain. Setting default unsets the previous default.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, required): Tracking domain name. Example: click.example.com
- `default` (`boolean`, optional): Use when no tracking domain is set on the sending domain (domain must be verified) Example: true
- `secure` (`boolean`, optional): Use HTTPS tracking links. Example: true
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"domain":"<domain>"}`

### `sparkpost_tracking_domain_verify`

Verify Tracking Domain · Write

Check the CNAME redirect of a tracking domain.
Returns results with verified, cname_status and compliance_status.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain` (`string`, required): Tracking domain name. Example: click.example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"domain":"<domain>"}`

### `sparkpost_transmission_send`

Send Email (Transmission) · Write

Send an email to one or more recipients by creating a SparkPost transmission, with inline content, a stored template or raw RFC 822 content.
Returns results with the transmission id, total_accepted_recipients and total_rejected_recipients (plus rcpt_to_errors when some recipients were invalid).
Use this to send. Set options.start_time through start_time to schedule up to 3 days ahead; cancel scheduled sends with sparkpost_transmissions_by_campaign_delete.
Prerequisite: the from address must be on a verified sending domain (see sparkpost_sending_domains_list).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amp_html` (`string`, optional): AMP for Email body (text/x-amp-html part). html or text must also be set. Example: <!doctype html><html ⚡4email>...</html>
- `attachments` (`array`, optional): Attachments for inline content. Each item has a file name, a MIME type and data, the file content as a base64 string without line breaks. Total content is limited to 20 MB. Example: [{"name": "invoice.pdf", "type": "application/pdf", "data": "JVBERi0xLjQK"}]
- `campaign_id` (`string`, optional): Campaign name, used to group metrics and to cancel scheduled sends. Max 64 bytes. Example: fall-sale-2026
- `click_tracking` (`boolean`, optional): Track link clicks. Defaults to the template or account setting. Example: true
- `description` (`string`, optional): Description of the transmission. Max 1024 bytes. Example: Order shipped notification
- `email_rfc822` (`string`, optional): A complete pre-built RFC 822 message to send instead of inline content or a template. Substitutions apply to the top-level headers and the first text, HTML and AMP parts. Example: Content-Type: text/plain
Subject: Hello

Hi {{address.name}}
- `from` (`string`, optional): Sender email address for inline content. The domain must be a verified sending domain. Required unless template_id or email_rfc822 is set. Example: support@mail.example.com
- `from_name` (`string`, optional): Sender display name shown with the from address. Example: Acme Support
- `headers` (`object`, optional): Extra email headers for inline content, as an object of header name to value. Do not set Subject, From, To, Reply-To, Content-Type or Content-Transfer-Encoding here. Example: {"X-Order-ID": "A1001"}
- `html` (`string`, optional): HTML body for inline content. Provide html, text or both. Example: Hi {{first_name}}, your order is on its way.

- `idempotency_key` (`string`, optional): Idempotency-Key header. Reuse the same key when retrying the same send so it is delivered once (1-255 letters, digits, '.', '_' or '-'; remembered for 24 hours) Example: 9f8b7c6d-1e2f-4a3b-8c9d-0e1f2a3b4c5d
- `inline_css` (`boolean`, optional): Inline the CSS from <style> blocks into the HTML. Example: true
- `inline_images` (`array`, optional): Inline images for inline content, referenced in the HTML as <img src="cid:NAME">. Each item has name, type and base64 data. Example: [{"name": "logo.png", "type": "image/png", "data": "iVBORw0KGgo="}]
- `ip_pool` (`string`, optional): IP pool to send from (dedicated IP accounts) Example: transactional
- `metadata` (`object`, optional): Transmission-level metadata returned in webhook and message events (and usable in templates). Max 10 KB. Example: {"order_id": "A1001"}
- `open_tracking` (`boolean`, optional): Track opens. Defaults to the template or account setting. Example: true
- `recipient_list_id` (`string`, optional): ID of a stored recipient list to send to instead of inline recipients (see sparkpost_recipient_lists_list). Set recipients or recipient_list_id. Example: newsletter-subscribers
- `recipients` (`array`, optional): Recipients to send to. Each item is an object with an address (a plain email string, or an object with email, an optional name, and header_to to send as CC/BCC), plus optional per-recipient tags, metadata and substitution_data. Leave empty and set recipient_list_id to send to a stored recipient list instead. Example: [{"address": {"email": "jane@example.com", "name": "Jane Doe"}, "substitution_data": {"first_name": "Jane"}}]
- `reply_to` (`string`, optional): Reply-To address for inline content. Example: help@example.com
- `return_path` (`string`, optional): Envelope FROM (bounce) address. Its domain must be a CNAME-verified sending domain. Example: bounces@mail.example.com
- `sandbox` (`boolean`, optional): Send from the SparkPost sandbox domain (only with template_id my-first-email; 5 lifetime messages; not on Enterprise) Example: false
- `skip_suppression` (`boolean`, optional): Skip the suppression list for this send (Enterprise accounts only) Example: false
- `start_time` (`string`, optional): Schedule the send for this time (ISO 8601, at most 3 days ahead). Leave empty to send now. Example: 2026-11-14T09:00:00-05:00
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `subject` (`string`, optional): Subject line for inline content. Required unless template_id or email_rfc822 is set. Supports the template language, e.g. {{first_name}}. Example: Your order has shipped
- `substitution_data` (`object`, optional): Transmission-level data for the template language. Recipient substitution_data takes precedence. Max 100 KB. Example: {"discount": "25%"}
- `template_id` (`string`, optional): ID of a stored template to send instead of inline content (see sparkpost_templates_list) Example: order-shipped
- `text` (`string`, optional): Plain-text body for inline content. Provide html, text or both. Example: Hi {{first_name}}, your order is on its way.
- `transactional` (`boolean`, optional): Mark the messages as transactional, so they ignore non-transactional unsubscribes and use transactional suppression entries. Example: true
- `use_draft_template` (`boolean`, optional): Send the draft version of template_id instead of the published one. The send fails if no draft exists. Example: false

Example input: `{}`

### `sparkpost_webhook_create`

Create Webhook · Write

Create an event webhook that POSTs batches of message events to your URL. SparkPost sends a test batch to the target on creation.
Returns results with the webhook id, name and links.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Webhook name. Example: Delivery events
- `target` (`string`, required): HTTPS or HTTP URL that receives event batches (ports 80/443) Example: https://example.com/sparkpost/events
- `active` (`boolean`, optional): Whether the webhook sends batches. Defaults to true. Example: true
- `auth_credentials` (`object`, optional): Credentials for basic auth: username and password. Example: {"username": "hook", "password": "s3cret"}
- `auth_request_details` (`object`, optional): OAuth 2.0 client-credentials details for auth_type oauth2: url, and body with client_id and client_secret. Example: {"url": "https://example.com/oauth/token", "body": {"client_id": "abc", "client_secret": "xyz"}}
- `auth_type` (`string`, optional): Authentication SparkPost uses when posting to target. Example: basic. One of: `none`, `basic`, `oauth2`.
- `custom_headers` (`object`, optional): Extra HTTP headers to send with each batch. Example: {"X-Customer-Id": "42"}
- `events` (`array`, optional): Event types to send, such as delivery, bounce, spam_complaint, open, initial_open, click, policy_rejection, delay, list_unsubscribe, link_unsubscribe. Leave empty for all. Example: ["delivery", "bounce", "spam_complaint"]
- `exception_subaccounts` (`array`, optional): Subaccount IDs to exclude (for primary-and-all-subaccounts webhooks) Example: [101]
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"name":"<name>","target":"<target>"}`

### `sparkpost_webhook_update`

Update Webhook · Write

Change an event webhook's name, target, events, status or authentication.
Returns results with the webhook id and links.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
- `active` (`boolean`, optional): Turn batch delivery on or off. Example: false
- `auth_credentials` (`object`, optional): Basic auth username and password. Example: {"username": "hook", "password": "s3cret"}
- `auth_request_details` (`object`, optional): OAuth 2.0 client-credentials details. Example: {"url": "https://example.com/oauth/token", "body": {"client_id": "abc", "client_secret": "xyz"}}
- `auth_type` (`string`, optional): Authentication used when posting to target. Example: none. One of: `none`, `basic`, `oauth2`.
- `custom_headers` (`object`, optional): Extra HTTP headers. Example: {"X-Customer-Id": "42"}
- `events` (`array`, optional): Event types to send. Example: ["delivery", "bounce"]
- `name` (`string`, optional): Webhook name. Example: Delivery events
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123
- `target` (`string`, optional): URL that receives event batches. Example: https://example.com/sparkpost/events

Example input: `{"id":"<id>"}`

### `sparkpost_webhook_validate`

Validate Webhook · Write

Send an example batch to a webhook's target URL and report the response.
Returns results with msg and response (status, headers, body from your endpoint).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
- `message` (`object`, optional): Example payload to send instead of the default sample. Example: {"msys": {}}
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"id":"<id>"}`

### `sparkpost_inbound_domain_delete`

Delete Inbound Domain · Destructive

Stop receiving inbound email for a domain.
Returns no content (204).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, required): Inbound domain. Example: inbound.example.com

Example input: `{"domain":"<domain>"}`

### `sparkpost_recipient_list_delete`

Delete Recipient List · Destructive

Delete a stored recipient list.
Returns an empty result. Fails with 409 while a transmission using the list is submitted or generating.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Recipient list ID (case sensitive) Example: newsletter-subscribers
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"id":"<id>"}`

### `sparkpost_relay_webhook_delete`

Delete Relay Webhook · Destructive

Delete a relay webhook; inbound mail for its domain is no longer forwarded.
Returns an empty result.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Relay webhook ID. Example: 12013026328707075

Example input: `{"id":"<id>"}`

### `sparkpost_sending_domain_delete`

Delete Sending Domain · Destructive

Remove a sending domain. Any later or scheduled transmission from it is rejected.
Returns no content (204).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, required): Sending domain name. Example: mail.example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"domain":"<domain>"}`

### `sparkpost_suppression_delete`

Delete Suppression · Destructive

Remove an email address from the suppression list so SparkPost can send to it again.
Returns no content (204). Entries added by SparkPost compliance cannot be removed (403).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `recipient` (`string`, required): Email address to remove. Example: jane@example.com
- `list_id` (`string`, optional): Remove only the entry for this mailing list. An empty value removes only the account-level entry; leave unset to remove all entries for the address. Example: newsletter.example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"recipient":"<recipient>"}`

### `sparkpost_template_delete`

Delete Template · Destructive

Delete a template, both draft and published versions.
Returns an empty result. Fails with 409 while a transmission using the template is submitted or generating.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Template ID (case sensitive) Example: order-shipped
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"id":"<id>"}`

### `sparkpost_tracking_domain_delete`

Delete Tracking Domain · Destructive

Remove a tracking domain.
Returns no content (204).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, required): Tracking domain name. Example: click.example.com
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"domain":"<domain>"}`

### `sparkpost_transmissions_by_campaign_delete`

Cancel Scheduled Transmissions by Campaign · Destructive

Cancel every scheduled transmission in a campaign that has not started generating.
Returns no content (204); deletion runs in the background and each cancelled message produces a bounce event with reason "Campaign cancelled".
Use this to stop scheduled sends created with sparkpost_transmission_send and a start_time.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `campaign_id` (`string`, required): Campaign ID whose scheduled transmissions to cancel. Example: fall-sale-2026
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"campaign_id":"<campaign_id>"}`

### `sparkpost_webhook_delete`

Delete Webhook · Destructive

Delete an event webhook.
Returns no content (204).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
- `subaccount_id` (`integer`, optional): Act as this subaccount: the request is sent with the X-MSYS-SUBACCOUNT header set to this subaccount ID. Use 0 for the primary account only. Leave empty when the API key belongs to the account you want to use. Example: 123

Example input: `{"id":"<id>"}`

## Related

Other Communication connectors ([all 132](/agentkit/connectors/?category=communication)):

- [Gmail](/agentkit/connectors/gmail/): Scalekit connector, OAuth, 48 tools
- [Slack](/agentkit/connectors/slack/): Scalekit connector, OAuth, 96 tools
- [Google Calendar](/agentkit/connectors/googlecalendar/): Scalekit connector, OAuth, 30 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
