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
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the SparkPost connection
In AgentKit > Connections, create a SparkPost connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'sparkpost'const identifier = 'user_123'// Generate an authorization link for the userconst { 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 callconst result = await actions.executeTool({connector,identifier,toolName: 'sparkpost_account_get',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "sparkpost"identifier = "user_123"# Generate an authorization link for the userlink_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 callresult = actions.execute_tool(tool_input={},tool_name="sparkpost_account_get",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach 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 toexecute_toolsparkpost_account_getRetrieve the SparkPost account's details, plan and options.Read-onlyGet 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-onlyPreview 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-onlyGet 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-onlyList 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_message_events_searchSearch per-message events (injection, delivery, bounce, open, click, spam complaint and more) from the last 10 days.Read-onlySearch Message Events
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.
Inputs
bounce_classesstring- Comma-separated bounce classification codes. Example: 10,30
campaignsstring- Comma-separated campaign IDs. Example: fall-sale-2026
cursorstring- Paging cursor from links.next of the previous response. Defaults to initial. Example: WycyMDE4LTExLTA1VDIyOjQ1OjM5LjAwMFonLCAnc3BjLTM4MTQ1MjY3MjMyNTA2NTEwJ10=
event_idsstring- Comma-separated event IDs. Example: 92356927693813856
eventsstring- Comma-separated event types, such as delivery, bounce, injection, delay, open, click, spam_complaint, policy_rejection, list_unsubscribe. Defaults to all. Example: bounce,delivery
fromstring- Start time (inclusive), YYYY-MM-DDTHH:MM:ssZ in UTC. Defaults to 24 hours ago. Example: 2026-11-12T00:00:00Z
from_addressesstring- Comma-separated friendly-from addresses. Example: orders@mail.example.com
messagesstring- Comma-separated message IDs. Example: 000443ee14578172be22
per_pageinteger- Results per page, 1 to 10,000. Defaults to 1000. Example: 100
reasonsstring- Comma-separated bounce, failure or rejection reason keywords. Example: mailbox full
recipient_domainsstring- Comma-separated recipient domains. Example: gmail.com
recipientsstring- Comma-separated recipient addresses. Example: jane@example.com
sending_domainsstring- Comma-separated sending domains. Example: mail.example.com
subaccount_idinteger- 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
subaccountsstring- Comma-separated subaccount IDs. Example: 101
subjectsstring- Comma-separated subject keywords. Example: shipped
templatesstring- Comma-separated template IDs. Example: order-shipped
tostring- End time (exclusive), YYYY-MM-DDTHH:MM:ssZ in UTC. Defaults to 1 minute ago. Example: 2026-11-13T00:00:00Z
transmissionsstring- Comma-separated transmission IDs. Example: 11668787484950529
sparkpost_metrics_breakdown_getGet deliverability and engagement metrics grouped by one dimension, such as recipient domain, campaign, template, sending domain or mailbox provider.Read-onlyGet 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-onlyGet 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-onlyGet 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
sparkpost_metrics_summary_getGet aggregate deliverability and engagement counts (sent, delivered, bounced, opened, clicked and more) over a time window.Read-onlyGet Metrics Summary
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.
Inputs
fromstringrequired- Start of the time window, in YYYY-MM-DDTHH:MM format (UTC unless timezone is set) Example: 2026-11-01T00:00
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
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_time_series_getGet deliverability and engagement metrics bucketed over time.Read-onlyGet Metrics Time Series
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.
Inputs
fromstringrequired- Start of the time window, in YYYY-MM-DDTHH:MM format (UTC unless timezone is set) Example: 2026-11-01T00:00
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
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_values_listList the values seen in a time window for one metrics dimension, such as the campaigns, templates or recipient domains that sent mail.Read-onlyList Metrics Filter Values
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.
Inputs
dimensionstringrequired- Which values to list. Example: campaignsone of
campaignstemplatesdomainssending-domainssubject-campaignsmailbox-providersmailbox-provider-regionsip-poolssending-ips fromstringrequired- Start of the window, YYYY-MM-DDTHH:MM. Example: 2026-11-01T00:00
limitinteger- Maximum number of values to return. Example: 50
matchstring- Only values containing this text. Example: sale
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_recipient_list_getRetrieve one stored recipient list, optionally with all of its recipients.Read-onlyGet Recipient List
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.
Inputs
idstringrequired- Recipient list ID (case sensitive) Example: newsletter-subscribers
show_recipientsboolean- true includes every recipient in the list. Example: true
subaccount_idinteger- 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
sparkpost_recipient_lists_listList the stored recipient lists in the account, without their recipients.Read-onlyList Recipient Lists
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.
Inputs
subaccount_idinteger- 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
sparkpost_relay_webhook_getRetrieve one relay webhook.Read-onlyGet Relay Webhook
Retrieve one relay webhook. Returns results with name, target, auth_type, match and custom_headers.
Inputs
idstringrequired- Relay webhook ID. Example: 12013026328707075
sparkpost_relay_webhooks_listList relay webhooks, which forward inbound email on an inbound domain to your URL.Read-onlyList Relay Webhooks
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).
Inputs
This tool takes no inputs.
sparkpost_sending_domain_getRetrieve one sending domain with its DNS records and verification status.Read-onlyGet Sending Domain
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).
Inputs
domainstringrequired- Sending domain name. Example: mail.example.com
subaccount_idinteger- 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
sparkpost_sending_domains_listList the sending domains in the account with their verification status.Read-onlyList Sending Domains
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.
Inputs
cname_statusstring- Filter by CNAME (bounce) status. Example: validone of
validinvalidunverifiedpending compliance_statusstring- Filter by compliance status. Example: validone of
validblocked dkim_statusstring- Filter by DKIM status. Example: validone of
validinvalidunverifiedpending is_default_bounce_domainboolean- Filter by default bounce domain. Example: false
mx_statusstring- Filter by MX status. Example: validone of
validinvalidunverifiedpending ownership_verifiedboolean- Filter by ownership verification. Example: true
subaccount_idinteger- 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
sparkpost_subaccount_getRetrieve one subaccount.Read-onlyGet Subaccount
Retrieve one subaccount. Returns results with id, name, status, compliance_status, ip_pool and options.
Inputs
idintegerrequired- Subaccount ID. Example: 101
sparkpost_subaccounts_listList the account's subaccounts.Read-onlyList Subaccounts
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.
Inputs
This tool takes no inputs.
sparkpost_suppression_getCheck whether one email address is suppressed and why.Read-onlyGet Suppression
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.
Inputs
recipientstringrequired- Email address to look up. Example: jane@example.com
subaccount_idinteger- 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
typesstring- Comma-separated types to match: transactional, non_transactional, open_tracking. Example: transactional,non_transactional
sparkpost_suppression_summary_getCount suppression entries by source.Read-onlyGet Suppression Summary
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.
Inputs
subaccount_idinteger- 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
sparkpost_suppressions_searchSearch the suppression list (addresses SparkPost will not send to) by date, domain, source, type or description.Read-onlySearch Suppressions
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.
Inputs
cursorstring- Paging cursor. Use initial for the first page, then the cursor from links in the previous response. Overrides page. Example: initial
descriptionstring- Text to match in descriptions. Example: hard bounce
description_strictboolean- true matches description exactly. Example: false
domainstring- Comma-separated recipient domains to match. Example: example.com
fromstring- Only entries last updated at or after this ISO 8601 datetime. Example: 2026-10-01T00:00:00Z
list_idstring- Only suppressions for this mailing list ID (RFC 2919). An empty value returns only account-level entries. Example: newsletter.example.com
pageinteger- Page number when paging without a cursor (up to 10,000 results) Example: 1
per_pageinteger- Results per page, 1 to 10,000. Defaults to 1000. Example: 100
sortstring- Sort by updated time. Defaults to desc. Example: descone of
ascdesc sourcesstring- 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_idinteger- 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
tostring- Only entries last updated before this ISO 8601 datetime. Defaults to now. Example: 2026-11-13T00:00:00Z
typesstring- Comma-separated types to match: transactional, non_transactional, open_tracking. Defaults to the two sending types. Example: transactional,non_transactional
sparkpost_template_getRetrieve one stored template, including its content (from, subject, html, text, headers) and options.Read-onlyGet Template
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.
Inputs
idstringrequired- Template ID (case sensitive) Example: order-shipped
draftboolean- true returns the draft version, false the published version. Example: false
subaccount_idinteger- 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
sparkpost_template_previewRender a stored template with substitution data, without sending anything.Read-onlyPreview Template
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.
Inputs
idstringrequired- Template ID (case sensitive) Example: order-shipped
draftboolean- true previews the draft version, false the published version. Example: true
subaccount_idinteger- 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_dataobject- Data passed to the template engine. Example: {"first_name": "Jane", "order_id": "A1001"}
sparkpost_templates_listList stored email templates in the account.Read-onlyList Templates
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.
Inputs
draftboolean- true returns draft versions, false returns published versions. Leave empty to return the most recently edited version of each. Example: false
shared_with_subaccountsboolean- true returns only templates shared with subaccounts, false only non-shared ones. Example: false
subaccount_idinteger- 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
sparkpost_tracking_domain_getRetrieve one tracking domain with its verification status.Read-onlyGet Tracking Domain
Retrieve one tracking domain with its verification status. Returns results with domain, port, secure, default and status.
Inputs
domainstringrequired- Tracking domain name. Example: click.example.com
subaccount_idinteger- 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
sparkpost_tracking_domains_listList the custom tracking (click and open) domains in the account.Read-onlyList Tracking Domains
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).
Inputs
defaultboolean- true returns only default tracking domains. Example: true
subaccountsstring- Comma-separated subaccount IDs to include (0 is the primary account) Example: 0,101
sparkpost_usage_getGet the account's sending usage against its daily, monthly and sandbox limits.Read-onlyGet Usage
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).
Inputs
This tool takes no inputs.
sparkpost_webhook_batch_status_getRead the delivery status of recent batches for a webhook (last 24 hours).Read-onlyGet Webhook Batch Status
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.
Inputs
idstringrequired- Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
limitinteger- Maximum number of batches to return. Defaults to 1000. Example: 50
subaccount_idinteger- 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
sparkpost_webhook_getRetrieve one event webhook.Read-onlyGet Webhook
Retrieve one event webhook. Returns results with name, target, events, active, auth_type, custom_headers and delivery timestamps.
Inputs
idstringrequired- Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
subaccount_idinteger- 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
timezonestring- IANA time zone for timestamps. Example: UTC
sparkpost_webhooks_listList the event webhooks configured in the account.Read-onlyList Webhooks
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.
Inputs
subaccount_idinteger- 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
timezonestring- IANA time zone for the returned timestamps. Defaults to UTC. Example: UTC
sparkpost_inbound_domain_createRegister a domain to receive inbound email through SparkPost (point its MX records at SparkPost).WriteCreate Inbound Domain
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.
Inputs
domainstringrequired- Domain to receive email for. Example: inbound.example.com
sparkpost_recipient_list_createCreate a stored recipient list for use in sparkpost_transmission_send recipient_list_id.WriteCreate Recipient List
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.
Inputs
recipientsarrayrequired- 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"}}]
attributesobject- Free-form metadata about the list, not used by the API. Example: {"source": "signup-form"}
descriptionstring- Description (max 1024 bytes) Example: Opted-in newsletter readers
idstring- Unique list ID (max 64 bytes). Generated when empty. Example: newsletter-subscribers
namestring- Display name (max 64 bytes). Defaults to the ID. Example: Newsletter subscribers
num_rcpt_errorsinteger- Maximum number of recipient errors to return. Example: 3
subaccount_idinteger- 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
sparkpost_recipient_list_updateUpdate a stored recipient list's name, description, attributes or recipients.WriteUpdate Recipient List
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.
- Idempotent
Inputs
idstringrequired- Recipient list ID (case sensitive) Example: newsletter-subscribers
attributesobject- Replacement metadata object. Example: {"source": "import"}
descriptionstring- New description. Example: Opted-in newsletter readers
namestring- New display name. Example: Newsletter subscribers
num_rcpt_errorsinteger- Maximum number of recipient errors to return. Example: 3
recipientsarray- Replacement recipients (replaces all existing ones). Same item shape as sparkpost_recipient_list_create. Example: [{"address": "jane@example.com"}]
subaccount_idinteger- 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
sparkpost_recipient_validateCheck whether an email address is deliverable before sending (syntax, domain, mailbox, role and disposable checks).WriteValidate Email Address
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.
Inputs
addressstringrequired- Email address to validate. Example: jane@example.com
sparkpost_relay_webhook_createForward inbound email received on an inbound domain to your URL as JSON.WriteCreate Relay Webhook
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).
Inputs
matchobjectrequired- Which inbound mail to relay: domain (the inbound domain) and protocol (SMTP) Example: {"protocol": "SMTP", "domain": "inbound.example.com"}
targetstringrequired- URL that receives relayed messages (port 80 or 443) Example: https://example.com/inbound
auth_request_detailsobject- 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_tokenstring- Token sent in the X-MessageSystems-Webhook-Token header. Example: 5ebe2294ecd0e0f08eab7690d2a6ee69
auth_typestring- Authentication used when posting. Defaults to none. Example: noneone of
noneoauth2 custom_headersobject- Extra HTTP headers to send. Example: {"X-Source": "sparkpost"}
namestring- Relay webhook name. Example: Support inbox
sparkpost_relay_webhook_updateChange a relay webhook's name, target, match or authentication.WriteUpdate Relay Webhook
Change a relay webhook's name, target, match or authentication. Returns results with the relay webhook id.
- Idempotent
Inputs
idstringrequired- Relay webhook ID. Example: 12013026328707075
auth_request_detailsobject- OAuth 2.0 client-credentials details. Example: {"url": "https://example.com/oauth/token", "body": {"client_id": "abc", "client_secret": "xyz"}}
auth_tokenstring- Token sent in the X-MessageSystems-Webhook-Token header. Example: 5ebe2294ecd0e0f08eab7690d2a6ee69
auth_typestring- Authentication used when posting. Example: noneone of
noneoauth2 custom_headersobject- Extra HTTP headers to send. Example: {"X-Source": "sparkpost"}
matchobject- Which inbound mail to relay: domain and protocol. Example: {"protocol": "SMTP", "domain": "inbound.example.com"}
namestring- Relay webhook name. Example: Support inbox
targetstring- URL that receives relayed messages. Example: https://example.com/inbound
sparkpost_sending_domain_createAdd a sending domain to the account.WriteCreate Sending Domain
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.
Inputs
domainstringrequired- Domain to send from. Example: mail.example.com
dkimobject- Your own DKIM key instead of a generated one: private, public, selector and optional headers. Example: {"private": "MIICXgIBAAKBgQC...", "public": "MIGfMA0GCSqGSIb3...", "selector": "scph0123"}
dkim_key_lengthinteger- DKIM key size in bits when generating. Defaults to 2048; use 1024 if your DNS host cannot store multi-string TXT records. Example: 2048one of
10242048 generate_dkimboolean- Generate a DKIM key pair. Defaults to true. Example: true
shared_with_subaccountsboolean- Let subaccounts send from this domain (primary-account domains only) Example: false
subaccount_idinteger- 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_domainstring- Tracking domain to associate (must belong to the same subaccount) Example: click.example.com
sparkpost_sending_domain_updateChange a sending domain's tracking domain, DKIM key, sharing or default bounce domain setting.WriteUpdate Sending Domain
Change a sending domain's tracking domain, DKIM key, sharing or default bounce domain setting. Returns results with domain and a message.
- Idempotent
Inputs
domainstringrequired- Sending domain name. Example: mail.example.com
dkimobject- Replacement DKIM configuration (private, public, selector, optional headers); verified before saving. Example: {"private": "MIICXgIBAAKBgQC...", "public": "MIGfMA0GCSqGSIb3...", "selector": "scph0124"}
is_default_bounce_domainboolean- Use as the default bounce domain (needs a valid CNAME or MX status; not on Enterprise) Example: true
shared_with_subaccountsboolean- Let subaccounts send from this domain. Example: true
subaccount_idinteger- 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_domainstring- Tracking domain to associate; empty string removes it. Example: click.example.com
sparkpost_sending_domain_verifyCheck a sending domain's DNS records (DKIM, CNAME) or start or complete mailbox verification.WriteVerify Sending Domain
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.
Inputs
domainstringrequired- Sending domain name. Example: mail.example.com
abuse_at_tokenstring- Token from the abuse@ verification email. Example: rcF4KlKFm5S2dDh4CcJ1xZ
abuse_at_verifyboolean- Email a verification link to abuse@domain. Example: false
cname_verifyboolean- Check the bounce CNAME record. Example: true
dkim_verifyboolean- Check the DKIM TXT record. Example: true
postmaster_at_tokenstring- Token from the postmaster@ verification email. Example: rcF4KlKFm5S2dDh4CcJ1xZ
postmaster_at_verifyboolean- Email a verification link to postmaster@domain. Example: false
subaccount_idinteger- 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_mailboxstring- Local part of the mailbox for verification_mailbox_verify (not postmaster or abuse) Example: admin
verification_mailbox_tokenstring- Token from the mailbox verification email, to complete verification. Example: rcF4KlKFm5S2dDh4CcJ1xZ
verification_mailbox_verifyboolean- Email a verification link to verification_mailbox@domain (not on Enterprise) Example: false
sparkpost_suppression_upsertAdd one email address to the suppression list, or update its entry, so SparkPost stops sending it that type of email.WriteAdd or Update Suppression
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.
- Idempotent
Inputs
recipientstringrequired- Email address to suppress. Example: jane@example.com
typestringrequired- Which mail to block: transactional, non_transactional, or open_tracking (stops open tracking only, mail still delivered) Example: non_transactionalone of
transactionalnon_transactionalopen_tracking descriptionstring- Reason for the suppression. Example: Unsubscribed by phone
list_idstring- Suppress only for this mailing list ID (RFC 2919). Leave empty for account-wide. Not allowed with open_tracking. Example: newsletter.example.com
subaccount_idinteger- 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
sparkpost_suppressions_bulk_upsertAdd or update up to 10,000 suppression entries in one call.WriteBulk Add or Update Suppressions
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.
- Idempotent
Inputs
recipientsarrayrequired- 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_idinteger- 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
sparkpost_template_createCreate a stored email template.WriteCreate Template
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.
Inputs
contentobjectrequired- 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": "<p>Hi {{first_name}}</p>"}
descriptionstring- Description of the template. Example: Sent when an order ships
idstring- Unique alphanumeric template ID (max 64 bytes). Generated from name when empty. Set id or name. Example: order-shipped
namestring- Display name (does not need to be unique). Set id or name. Example: Order shipped
optionsobject- Template options, overridable per transmission: open_tracking, click_tracking and transactional (booleans) Example: {"open_tracking": true, "click_tracking": true, "transactional": true}
shared_with_subaccountsboolean- Let subaccounts use this template (primary-account templates only) Example: false
subaccount_idinteger- 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
sparkpost_template_updateUpdate a template's draft, overwrite its published version, or publish the current draft.WriteUpdate or Publish Template
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.
- Idempotent
Inputs
idstringrequired- Template ID (case sensitive) Example: order-shipped
contentobject- 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}}"}
descriptionstring- New description. Example: Sent when an order ships
namestring- New display name. Example: Order shipped v2
optionsobject- Template options: open_tracking, click_tracking and transactional. Example: {"click_tracking": false}
publishedboolean- Set to true (with no other fields) to publish the current draft as the new published version. Example: true
shared_with_subaccountsboolean- Let subaccounts use this template (updates both versions) Example: true
subaccount_idinteger- 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_publishedboolean- true overwrites the published version directly; otherwise the draft is updated. Example: false
sparkpost_tracking_domain_createAdd a custom tracking domain that wraps open pixels and links.WriteCreate Tracking Domain
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.
Inputs
domainstringrequired- Tracking domain name. Example: click.example.com
secureboolean- Use HTTPS tracking links. Defaults to false. Example: true
subaccount_idinteger- 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
sparkpost_tracking_domain_updateChange whether a tracking domain uses HTTPS or is the default.WriteUpdate Tracking Domain
Change whether a tracking domain uses HTTPS or is the default. Returns results with domain. Setting default unsets the previous default.
- Idempotent
Inputs
domainstringrequired- Tracking domain name. Example: click.example.com
defaultboolean- Use when no tracking domain is set on the sending domain (domain must be verified) Example: true
secureboolean- Use HTTPS tracking links. Example: true
subaccount_idinteger- 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
sparkpost_tracking_domain_verifyCheck the CNAME redirect of a tracking domain.WriteVerify Tracking Domain
Check the CNAME redirect of a tracking domain. Returns results with verified, cname_status and compliance_status.
Inputs
domainstringrequired- Tracking domain name. Example: click.example.com
subaccount_idinteger- 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
sparkpost_transmission_sendSend an email to one or more recipients by creating a SparkPost transmission, with inline content, a stored template or raw RFC 822 content.WriteSend Email (Transmission)
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).
Inputs
amp_htmlstring- AMP for Email body (text/x-amp-html part). html or text must also be set. Example: <!doctype html><html ⚡4email>...</html>
attachmentsarray- 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_idstring- Campaign name, used to group metrics and to cancel scheduled sends. Max 64 bytes. Example: fall-sale-2026
click_trackingboolean- Track link clicks. Defaults to the template or account setting. Example: true
descriptionstring- Description of the transmission. Max 1024 bytes. Example: Order shipped notification
email_rfc822string- 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}}
fromstring- 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_namestring- Sender display name shown with the from address. Example: Acme Support
headersobject- 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"}
htmlstring- HTML body for inline content. Provide html, text or both. Example: <p>Hi {{first_name}}, your order is on its way.</p>
idempotency_keystring- 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_cssboolean- Inline the CSS from <style> blocks into the HTML. Example: true
inline_imagesarray- 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_poolstring- IP pool to send from (dedicated IP accounts) Example: transactional
metadataobject- Transmission-level metadata returned in webhook and message events (and usable in templates). Max 10 KB. Example: {"order_id": "A1001"}
open_trackingboolean- Track opens. Defaults to the template or account setting. Example: true
recipient_list_idstring- 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
recipientsarray- 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_tostring- Reply-To address for inline content. Example: help@example.com
return_pathstring- Envelope FROM (bounce) address. Its domain must be a CNAME-verified sending domain. Example: bounces@mail.example.com
sandboxboolean- Send from the SparkPost sandbox domain (only with template_id my-first-email; 5 lifetime messages; not on Enterprise) Example: false
skip_suppressionboolean- Skip the suppression list for this send (Enterprise accounts only) Example: false
start_timestring- 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_idinteger- 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
subjectstring- 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_dataobject- Transmission-level data for the template language. Recipient substitution_data takes precedence. Max 100 KB. Example: {"discount": "25%"}
template_idstring- ID of a stored template to send instead of inline content (see sparkpost_templates_list) Example: order-shipped
textstring- Plain-text body for inline content. Provide html, text or both. Example: Hi {{first_name}}, your order is on its way.
transactionalboolean- Mark the messages as transactional, so they ignore non-transactional unsubscribes and use transactional suppression entries. Example: true
use_draft_templateboolean- Send the draft version of template_id instead of the published one. The send fails if no draft exists. Example: false
sparkpost_webhook_createCreate an event webhook that POSTs batches of message events to your URL.WriteCreate Webhook
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.
Inputs
namestringrequired- Webhook name. Example: Delivery events
targetstringrequired- HTTPS or HTTP URL that receives event batches (ports 80/443) Example: https://example.com/sparkpost/events
activeboolean- Whether the webhook sends batches. Defaults to true. Example: true
auth_credentialsobject- Credentials for basic auth: username and password. Example: {"username": "hook", "password": "s3cret"}
auth_request_detailsobject- 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_typestring- Authentication SparkPost uses when posting to target. Example: basicone of
nonebasicoauth2 custom_headersobject- Extra HTTP headers to send with each batch. Example: {"X-Customer-Id": "42"}
eventsarray- 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_subaccountsarray- Subaccount IDs to exclude (for primary-and-all-subaccounts webhooks) Example: [101]
subaccount_idinteger- 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
sparkpost_webhook_updateChange an event webhook's name, target, events, status or authentication.WriteUpdate Webhook
Change an event webhook's name, target, events, status or authentication. Returns results with the webhook id and links.
- Idempotent
Inputs
idstringrequired- Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
activeboolean- Turn batch delivery on or off. Example: false
auth_credentialsobject- Basic auth username and password. Example: {"username": "hook", "password": "s3cret"}
auth_request_detailsobject- OAuth 2.0 client-credentials details. Example: {"url": "https://example.com/oauth/token", "body": {"client_id": "abc", "client_secret": "xyz"}}
auth_typestring- Authentication used when posting to target. Example: noneone of
nonebasicoauth2 custom_headersobject- Extra HTTP headers. Example: {"X-Customer-Id": "42"}
eventsarray- Event types to send. Example: ["delivery", "bounce"]
namestring- Webhook name. Example: Delivery events
subaccount_idinteger- 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
targetstring- URL that receives event batches. Example: https://example.com/sparkpost/events
sparkpost_webhook_validateSend an example batch to a webhook's target URL and report the response.WriteValidate Webhook
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).
Inputs
idstringrequired- Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
messageobject- Example payload to send instead of the default sample. Example: {"msys": {}}
subaccount_idinteger- 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
sparkpost_inbound_domain_deleteStop receiving inbound email for a domain.DestructiveDelete Inbound Domain
Stop receiving inbound email for a domain. Returns no content (204).
- Idempotent
Inputs
domainstringrequired- Inbound domain. Example: inbound.example.com
sparkpost_recipient_list_deleteDelete a stored recipient list.DestructiveDelete Recipient List
Delete a stored recipient list. Returns an empty result. Fails with 409 while a transmission using the list is submitted or generating.
- Idempotent
Inputs
idstringrequired- Recipient list ID (case sensitive) Example: newsletter-subscribers
subaccount_idinteger- 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
sparkpost_relay_webhook_deleteDelete a relay webhook; inbound mail for its domain is no longer forwarded.DestructiveDelete Relay Webhook
Delete a relay webhook; inbound mail for its domain is no longer forwarded. Returns an empty result.
- Idempotent
Inputs
idstringrequired- Relay webhook ID. Example: 12013026328707075
sparkpost_sending_domain_deleteRemove a sending domain.DestructiveDelete Sending Domain
Remove a sending domain. Any later or scheduled transmission from it is rejected. Returns no content (204).
- Idempotent
Inputs
domainstringrequired- Sending domain name. Example: mail.example.com
subaccount_idinteger- 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
sparkpost_suppression_deleteRemove an email address from the suppression list so SparkPost can send to it again.DestructiveDelete Suppression
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).
- Idempotent
Inputs
recipientstringrequired- Email address to remove. Example: jane@example.com
list_idstring- 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_idinteger- 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
sparkpost_template_deleteDelete a template, both draft and published versions.DestructiveDelete Template
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.
- Idempotent
Inputs
idstringrequired- Template ID (case sensitive) Example: order-shipped
subaccount_idinteger- 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
sparkpost_tracking_domain_deleteRemove a tracking domain.DestructiveDelete Tracking Domain
Remove a tracking domain. Returns no content (204).
- Idempotent
Inputs
domainstringrequired- Tracking domain name. Example: click.example.com
subaccount_idinteger- 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
sparkpost_transmissions_by_campaign_deleteCancel every scheduled transmission in a campaign that has not started generating.DestructiveCancel Scheduled Transmissions by Campaign
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.
- Idempotent
Inputs
campaign_idstringrequired- Campaign ID whose scheduled transmissions to cancel. Example: fall-sale-2026
subaccount_idinteger- 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
sparkpost_webhook_deleteDelete an event webhook.DestructiveDelete Webhook
Delete an event webhook. Returns no content (204).
- Idempotent
Inputs
idstringrequired- Webhook ID. Example: 12affc24-f183-11e3-9234-3c15c2c818c2
subaccount_idinteger- 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
No tools match.