API reference: HubSpot Marketing Email

HubSpot Marketing Email is a read + guardrailed write connector, called via tools/call over POST /hubspot-email/mcp. The connector is connected through OAuth (HubSpot login; see Forbind HubSpot Marketing Email).

Endpoint: https://mcp.consile.ai/hubspot-email/mcp. HubSpot Marketing Email is its own named connector with only its own tools. It is single-instance: one HubSpot portal per subscription.

Tier requirement. The OAuth scopes content and marketing-email require the connected HubSpot portal to be on Marketing Hub Professional or Enterprise. Sending and publishing emails additionally needs Enterprise or the transactional-email add-on. A Starter or Free portal cannot grant the required scopes, so the connection does not complete.

Write safety: guardrail model

The connector divides its write tools into two groups based on reversibility and audience impact. Runs freely (no confirmation needed):

create_email: creates an unpublished draft; never sends.
update_email_draft: edits the draft buffer only; the live/published version is unchanged.
clone_email: produces a new draft; no audience impact.
create_email_ab_variation: creates a draft variant; does not send.

Requires confirm: true:

update_email: edits the live/current record (can change the audience or content of an already-published or scheduled email).
publish_email: sends the email to real recipients. Highest-risk action.
unpublish_email: cancels a scheduled send or unpublishes a published email.
delete_email: archives the email.
reset_email_draft: discards the draft’s unpublished changes and resets the draft to the latest published version (destructive; cannot be undone).
restore_email_revision_to_draft: overwrites the draft buffer with a previous revision.
restore_email_revision: replaces the live version with a previous revision.

Without confirm: true, every confirm-gated tool returns a dry-run preview and calls no HubSpot API. Sending is only reachable through the explicitly-confirmed publish_email tool. create_email and update_email_draft can never publish or schedule a send: neither tool accepts a state, publish date or send setting. This is a safety default built into the connector’s tools, not an unbreakable platform gate. See Write tools & guardrails for the full cross-connector policy.

Preview shape

When a write action requires confirmation but confirm is omitted or false, the tool returns this shape instead of calling HubSpot:

{
  "preview": {
    "action": "publish_email",
    "summary": "PUBLISH/SEND marketing email 123456 to its configured recipients.",
    "request": { "method": "…", "path": "…", "body": {} },
    "confirmHint": "Re-run the same call with confirm: true to apply this change."
  }
}

summary describes the change, and request shows the write that would be sent to HubSpot. To apply, re-run the identical call with confirm: true added. The preview is a normal successful tool result (isError is not set). The publish_email preview names the email but not its recipients or send time; read them with get_email before confirming.

Tool titles and annotations

tools/list returns every tool with a title and MCP annotations:

Tools	`readOnlyHint`	`destructiveHint`	`openWorldHint`
The 8 read tools	`true`	`false`	`false`
`create_email`, `update_email`, `update_email_draft`, `clone_email`, `create_email_ab_variation`, `reset_email_draft`, `restore_email_revision_to_draft`	`false`	`true`	`false`
`restore_email_revision`, `publish_email`, `unpublish_email`, `delete_email`	`false`	`true`	`true`

openWorldHint: true marks the four tools that reach recipients or replace what they already received. Draft writes are marked destructive because they are writes. Some clients ask the user to approve each call of a tool marked destructiveHint: true; that prompt comes from the client and is separate from the confirm guardrail. The endpoint also lists one system tool, connect_account (not prefixed, no arguments, readOnlyHint: true). It returns a link, valid for 10 minutes, that the user opens in a browser to connect or reconnect the HubSpot account. It is listed for every signed-in user; if the user’s company does not subscribe to the connector, it returns a purchase message instead of a link. For a subscribed account where the user has all tools, tools/list therefore returns 20 entries: the 19 connector tools plus connect_account.

Shared parameters

Paging

List tools return a HubSpot { total, results, paging } envelope. To fetch the next page, pass the cursor from paging.next.after as the after argument.

integer

default:"20"

Max items to return in this page (1-100).

string

Paging cursor from a previous response’s paging.next.after.

Email id

Most per-email tools take emailId (a string holding HubSpot’s numeric email id). Two exceptions: clone_email takes the source email as id, and create_email_ab_variation takes it as contentId.

Timestamps

Time-range fields accept ISO 8601 strings, e.g. 2026-01-01T00:00:00Z.

Responses

Tools return HubSpot’s own response bodies unchanged. The field lists below are examples, not a fixed schema. When HubSpot answers with an empty body (HTTP 204), the result text is null; a null result without isError means the action succeeded.

Read tools (8 total)

list_emails

List marketing emails with paging and filtering. Pass includeStats: true to include aggregated post-send statistics per email in the same response.

integer

default:"20"

string

Field to sort by; prefix with - for descending, e.g. -updatedAt.

boolean

List archived emails instead of live ones.

string

Filter by campaign GUID.

string

Filter by HubSpot email type (free string passed to HubSpot), e.g. BATCH_EMAIL, AB_EMAIL, AUTOMATED_EMAIL, RSS_EMAIL.

boolean

Filter by published state.

boolean

Include post-send statistics in each result.

string

ISO 8601 lower bound on creation time.

string

ISO 8601 upper bound on creation time.

string

ISO 8601 lower bound on update time.

string

ISO 8601 upper bound on update time.

string

ISO 8601 lower bound on publish time.

string

ISO 8601 upper bound on publish time.

Returns: { total, results[], paging }; results include fields such as the email id, name, subject, type, published state, campaign, language and (when requested) aggregated send stats.

get_email

Get the full details of one marketing email by id (the live/current version).

string

required

boolean

Include aggregated post-send statistics in the response.

boolean

Include per-variant stats for A/B emails.

boolean

Look up an archived email.

Returns: The email object, with fields such as id, name, subject, type, state, publishDate, from, to, content, campaign, language and (when requested) stats.

get_email_draft

Read the current unpublished draft (working copy) of a marketing email to inspect pending edits before publishing.

string

required

Returns: The draft object for the email, including any edits not yet visible on the live version.

list_email_revisions

List the historical revisions (version snapshots) of a marketing email, with paging.

string

required

integer

default:"20"

string

Paging cursor: revisions before this token.

string

Returns: { results[], paging }; each revision includes fields such as the revision id, created time and a snapshot of the email at that point.

get_email_revision

Get a single historical revision by revision id.

string

required

string

required

The revision/version id (from list_email_revisions).

Returns: The full revision snapshot.

get_email_ab_variation

Get the opposite A/B variation of an A/B marketing email: given variation A it returns B, and vice versa.

string

required

Returns: The counterpart variation object.

get_email_statistics

Get aggregated post-send statistics across emails sent in a time span: sent, delivered, open, click, bounce counters and ratios, plus the list of email ids sent. Matches the in-app Email Performance view.

string

Start of the time span (ISO 8601).

string

End of the time span (ISO 8601).

string[]

Restrict to these email ids. Omit to include all sent emails in the span.

string

Restrict the returned statistic properties to one named field.

Returns: Aggregated counters and ratios (for example sent, delivered, open rate, click rate, bounce rate, unsubscribe rate) and the email ids included.

get_email_statistics_histogram

Get time-bucketed statistics over a span at a chosen interval. Each bucket carries the aggregated stats of emails sent in that interval. Useful for charting performance trends.

string

Bucket size. One of: HOUR, DAY, WEEK, MONTH, QUARTER, YEAR, MINUTE, QUARTER_HOUR, SECOND.

string

Start of the time span (ISO 8601).

string

End of the time span (ISO 8601).

string[]

Restrict to these email ids.

Returns: HubSpot’s response unchanged: an object with total and results, where each result covers one interval (start and end) and carries the aggregated statistics of emails sent in that interval.

Write tools (11 total)

Write tools call the HubSpot Marketing Emails API. Creating an email as a draft, editing the draft buffer, cloning and creating an A/B variation run freely. Editing the live/current version (update_email), sending or publishing (publish_email), cancelling a send (unpublish_email), archiving (delete_email) and discarding or restoring work (reset_email_draft, restore_email_revision_to_draft, restore_email_revision) require confirm: true. Without it the tool returns a preview and calls no API. See Write tools & guardrails.

Shared writable fields

The create_email, update_email, and update_email_draft tools share a common set of content and sender fields:

string

Email subject line.

string

Locale code, e.g. en, en-us, da-dk.

string

Marketing campaign GUID to associate the email with.

integer

Business Unit id (requires the Business Units / Brands add-on).

integer

Destination folder id.

string

Sender display name.

string

Reply-to email address.

string

Custom reply-to email address.

string[]

Contact list ids to send to. An empty array is ignored, so the connector cannot clear an email’s recipient lists. Exclusion lists cannot be set.

string

Path to the template or theme file the email uses.

string

Plain-text version of the email body.

The email’s module/HTML body, excluded lists, subscription settings and publish date cannot be set through the connector. There are no tools for listing contact lists, campaigns or folders, so ids must come from HubSpot or from an existing email returned by get_email.

create_email

Create a new marketing email as an unpublished draft. The state is forced to DRAFT on creation: this tool can never publish or schedule a send. Only name is required. Publish later with publish_email. Runs freely. No confirmation needed.

string

required

Internal name of the email.

string

integer

string

string[]

string

Returns: The newly created email object with state: "DRAFT".

update_email

Sparse-update a marketing email’s fields on the live/current version, not just the draft buffer. Does not publish or send, but it can change the audience or content of an already-published or scheduled email. Requires confirm: true.

string

required

string

integer

string

string[]

string

boolean

Set true to apply. Omit or false to receive a preview.

Returns: The updated email object, or a preview if confirm is not true.

update_email_draft

Create or update only the draft (working copy) of a marketing email without touching the live/published version. Does not publish or send. Runs freely. No confirmation needed.

string

required

string

integer

string

string[]

string

Returns: The updated draft object.

clone_email

Clone an existing marketing email into a new draft, optionally renaming it and setting a locale. Runs freely. No confirmation needed.

string

required

The id of the marketing email to clone.

string

Name for the new cloned email.

string

Locale for the clone, e.g. da-dk.

Returns: The newly created draft clone.

create_email_ab_variation

Create an A/B test variation of a marketing email. The variation is created as a draft variant and does not send. Runs freely. No confirmation needed.

string

required

The id of the email to create an A/B variation of.

string

required

Name of the new variation.

Returns: The newly created draft A/B variation object.

Confirm-gated tools: return value

The six tools below share one return contract. Without confirm: true they return a preview. With confirm: true they return HubSpot’s response; when HubSpot answers with an empty body (HTTP 204), the result text is null. A null result without isError means the action succeeded.

reset_email_draft

Discard the draft’s unpublished changes, resetting the draft back to the latest published version. This cannot be undone. Requires confirm: true.

string

required

boolean

Set true to apply. Omit or false to receive a preview.

restore_email_revision_to_draft

Copy a previous revision’s content into the current draft without publishing. Overwrites the draft buffer. Requires confirm: true.

string

required

string

required

The revision id to restore into the draft (from list_email_revisions).

boolean

Set true to apply. Omit or false to receive a preview.

restore_email_revision

Restore a previous revision as the new current/live version of the marketing email. Replaces the live version. Requires confirm: true.

string

required

string

required

The revision id to restore (from list_email_revisions).

boolean

Set true to apply. Omit or false to receive a preview.

publish_email

Publish or send the marketing email to its configured recipients. This is the highest-risk action: it sends real email to the customer’s contact lists. It acts on the recipients, state and publish date already set on the email; this tool does not set them. Needs the marketing-email (or transactional-email) scope on a Marketing Hub Enterprise portal (or transactional-email add-on). Requires confirm: true.

string

required

boolean

Set true to apply. Omit or false to receive a preview.

unpublish_email

Unpublish a published email or cancel a scheduled send. Requires confirm: true.

string

required

boolean

Set true to apply. Omit or false to receive a preview.

delete_email

Delete a marketing email (HubSpot archives it). Archived emails can still be read with get_email or list_emails and archived: true, but the connector has no tool to restore an archived email. Requires confirm: true.

string

required

boolean

Set true to apply. Omit or false to receive a preview.

Code examples

{
  "name": "hubspot-email__list_emails",
  "arguments": {
    "isPublished": false,
    "sort": "-updatedAt",
    "limit": 20
  }
}

{
  "name": "hubspot-email__get_email_statistics",
  "arguments": {
    "startTimestamp": "2026-05-01T00:00:00Z",
    "endTimestamp": "2026-05-31T23:59:59Z"
  }
}

{
  "name": "hubspot-email__update_email_draft",
  "arguments": {
    "emailId": "123456",
    "subject": "New subject line",
    "fromName": "<company name>"
  }
}

{
  "name": "hubspot-email__publish_email",
  "arguments": {
    "emailId": "123456"
  }
}

{
  "name": "hubspot-email__publish_email",
  "arguments": {
    "emailId": "123456",
    "confirm": true
  }
}

{
  "name": "hubspot-email__clone_email",
  "arguments": {
    "id": "123456",
    "cloneName": "Summer Newsletter (DK)",
    "language": "da-dk"
  }
}

Tool names are namespaced hubspot-email__<tool> in Claude/ChatGPT (the AI invokes these automatically). The bare names, e.g. publish_email, are used in this reference for readability.

Limits and errors

HubSpot limits public apps to about 110 requests per 10 seconds per connected HubSpot account. A call that exceeds HubSpot’s rate limit can fail with Tool invocation failed.; wait a few seconds and try again.
Consile renews the HubSpot access automatically.

If the stored HubSpot access has expired or been revoked (for example because the Consile app was uninstalled in HubSpot), the result has isError: true and one of these messages:

HubSpot access token has expired; reconnect required
HubSpot rejected the access token (401); reconnect required

The customer then reconnects the connector in the portal or through connect_account. For other upstream failures (a 403 because the portal’s plan or scopes do not cover the call; validation errors; unknown ids; timeouts), HubSpot’s error details are not passed through to the client: the tool result has isError: true and the text Tool invocation failed. If the connector is bought but not connected, a call instead returns a link to connect it. A signed-in user who has not been assigned a seat on HubSpot Marketing Email still sees the tools in tools/list, but every call returns a message asking them to have an administrator assign them under Team in the portal. See Errors & limits.

Revocation

Disconnecting in the Consile portal (Afbryd connector / Disconnect connector) deletes the stored access immediately. To remove the access at HubSpot as well, the customer uninstalls the Consile HubSpot Marketing Email app in their HubSpot portal settings. This app is separate from the HubSpot CMS connector’s app (Consile HubSpot CMS); uninstalling one does not affect the other. To reconnect after an uninstall or revoke, the customer disconnects and connects again in the portal, or calls connect_account.

Introduction

Connect an MCP client

API reference

API reference: HubSpot Marketing Email

Write safety: guardrail model

Preview shape

Tool titles and annotations

Shared parameters

Paging

Email id

Timestamps

Responses

Read tools (8 total)

list_emails

get_email

get_email_draft

list_email_revisions

get_email_revision

get_email_ab_variation

get_email_statistics

get_email_statistics_histogram

Write tools (11 total)

Shared writable fields

create_email

update_email

update_email_draft

clone_email

create_email_ab_variation

Confirm-gated tools: return value

reset_email_draft

restore_email_revision_to_draft

restore_email_revision

publish_email

unpublish_email

delete_email

Code examples

Limits and errors

Revocation

​Write safety: guardrail model

​Preview shape

​Tool titles and annotations

​Shared parameters

​Paging

​Email id

​Timestamps

​Responses

​Read tools (8 total)

​list_emails

​get_email

​get_email_draft

​list_email_revisions

​get_email_revision

​get_email_ab_variation

​get_email_statistics

​get_email_statistics_histogram

​Write tools (11 total)

​Shared writable fields

​create_email

​update_email

​update_email_draft

​clone_email

​create_email_ab_variation

​Confirm-gated tools: return value

​reset_email_draft

​restore_email_revision_to_draft

​restore_email_revision

​publish_email

​unpublish_email

​delete_email

​Code examples

​Limits and errors

​Revocation

Write safety: guardrail model

Preview shape

Tool titles and annotations

Shared parameters

Paging

Email id

Timestamps

Responses

Read tools (8 total)

list_emails

get_email

get_email_draft

list_email_revisions

get_email_revision

get_email_ab_variation

get_email_statistics

get_email_statistics_histogram

Write tools (11 total)

Shared writable fields

create_email

update_email

update_email_draft

clone_email

create_email_ab_variation

Confirm-gated tools: return value

reset_email_draft

restore_email_revision_to_draft

restore_email_revision

publish_email

unpublish_email

delete_email

Code examples

Limits and errors

Revocation