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.

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 and will fail at the HubSpot consent screen.

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: soft-archives the email.
reset_email_draft: discards unsaved draft changes (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 WritePreview dry-run 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: the state/publishDate/sendOnPublish fields are intentionally absent from those tools. This is a designed-in safety default (connector-local application logic), not an unbreakable platform gate. See Handlinger & guardrails for the full cross-connector policy.

WritePreview 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": "POST",
      "path": "/marketing/v3/emails/123456/publish",
      "body": {}
    },
    "confirmHint": "Re-run the same call with confirm: true to apply this change."
  }
}

To apply, re-run the identical call with confirm: true added.

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.

limit

integer

default:"20"

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

after

string

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

Email id

All per-email tools accept emailId: the numeric HubSpot marketing email id.

Timestamps

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

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.

limit

integer

default:"20"

after

string

sort

string

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

archived

boolean

List archived emails instead of live ones.

campaign

string

Filter by campaign GUID.

type

string

Filter by email type: BATCH_EMAIL, AB_EMAIL, AUTOMATED_EMAIL, RSS_EMAIL.

isPublished

boolean

Filter by published state.

includeStats

boolean

Include post-send statistics in each result.

createdAfter

string

ISO 8601 lower bound on creation time.

createdBefore

string

ISO 8601 upper bound on creation time.

updatedAfter

string

ISO 8601 lower bound on update time.

updatedBefore

string

ISO 8601 upper bound on update time.

publishedAfter

string

ISO 8601 lower bound on publish time.

publishedBefore

string

ISO 8601 upper bound on publish time.

Returns: { total, results[], paging }: each result includes 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).

emailId

string

required

includeStats

boolean

Include aggregated post-send statistics in the response.

variantStats

boolean

Include per-variant stats for A/B emails.

archived

boolean

Look up an archived email.

Returns: Full email object: 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.

emailId

string

required

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

list_email_revisions

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

emailId

string

required

limit

integer

default:"20"

before

string

Paging cursor: revisions before this token.

after

string

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

get_email_revision

Get a single historical revision by revision id.

emailId

string

required

revisionId

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.

emailId

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.

startTimestamp

string

Start of the time span (ISO 8601).

endTimestamp

string

End of the time span (ISO 8601).

emailIds

string[]

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

property

string

Restrict the returned statistic properties to one named field.

Returns: Aggregated counters and ratios: 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.

interval

string

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

startTimestamp

string

Start of the time span (ISO 8601).

endTimestamp

string

End of the time span (ISO 8601).

emailIds

string[]

Restrict to these email ids.

Returns: An array of time-bucketed stat objects, each with a timestamp and the same counters as get_email_statistics.

Write tools (11 total)

Write tools call the HubSpot Marketing Emails API. Drafts and safe edits run freely. Actions that publish to the live site, send to recipients, cancel, delete, or overwrite draft work require confirm: true. Without it the tool returns a WritePreview and calls no API. See Handlinger & guardrails.

Shared writable fields

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

subject

string

Email subject line.

language

string

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

campaign

string

Marketing campaign GUID to associate the email with.

businessUnitId

integer

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

folderIdV2

integer

Destination folder id.

fromName

string

Sender display name.

replyTo

string

Reply-to email address.

customReplyTo

string

Custom reply-to email address.

contactListIds

string[]

Contact list ids to send to (assembled into to.contactLists.include).

templatePath

string

Path to the template or theme file the email uses.

plainTextVersion

string

Plain-text version of the email body.

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.

name

string

required

Internal name of the email.

subject

string

language

string

campaign

string

businessUnitId

integer

folderIdV2

integer

fromName

string

replyTo

string

customReplyTo

string

contactListIds

string[]

templatePath

string

plainTextVersion

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.

emailId

string

required

name

string

subject

string

language

string

campaign

string

businessUnitId

integer

folderIdV2

integer

fromName

string

replyTo

string

customReplyTo

string

contactListIds

string[]

templatePath

string

plainTextVersion

string

confirm

boolean

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

Returns: The updated email object, or a WritePreview 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.

emailId

string

required

name

string

subject

string

language

string

campaign

string

businessUnitId

integer

folderIdV2

integer

fromName

string

replyTo

string

customReplyTo

string

contactListIds

string[]

templatePath

string

plainTextVersion

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.

cloneName

string

Name for the new cloned email.

language

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.

contentId

string

required

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

variationName

string

required

Name of the new variation.

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

reset_email_draft

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

emailId

string

required

confirm

boolean

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

restore_email_revision_to_draft

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

emailId

string

required

revisionId

string

required

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

confirm

boolean

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

restore_email_revision

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

emailId

string

required

revisionId

string

required

The revision id to restore (from list_email_revisions).

confirm

boolean

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

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. Requires confirm: true. Needs the marketing-email (or transactional-email) scope on a Marketing Hub Enterprise portal (or transactional-email add-on). Requires confirm: true.

emailId

string

required

confirm

boolean

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

unpublish_email

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

emailId

string

required

confirm

boolean

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

delete_email

Delete a marketing email (soft-archive). The email can be retrieved from the archived state, but deletion is treated as irreversible here. Requires confirm: true.

emailId

string

required

confirm

boolean

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

Code examples

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

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.

An expired or revoked access token surfaces as AccessTokenExpiredError. HubSpot access tokens are short-lived (~30 minutes) and renewed automatically in the background via the stored refresh token. If automatic renewal fails, reconnect via the portal. See Errors & limits.

Revocation

There is no upstream revoke in the portal in v1. To revoke access, uninstall the Consile app in your HubSpot portal settings. Disconnecting in the Consile portal deletes the stored token immediately, but the HubSpot app authorization remains until you uninstall it from HubSpot.

​Write safety: guardrail model

​WritePreview shape

​Shared parameters

​Paging

​Email id

​Timestamps

​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

​reset_email_draft

​restore_email_revision_to_draft

​restore_email_revision

​publish_email

​unpublish_email

​delete_email

​Code examples

​Revocation

Write safety: guardrail model

WritePreview shape

Shared parameters

Paging

Email id

Timestamps

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

reset_email_draft

restore_email_revision_to_draft

restore_email_revision

publish_email

unpublish_email

delete_email

Code examples

Revocation