canonical: https://jentic.com/apis/hubspot.com/hubspot-marketing-emails-v3

# HubSpot Marketing Emails V3

The HubSpot Marketing Emails V3 API is the rollout-155892 build of the marketing email endpoints, covering the same draft, AB-test, revision, publish, and statistics surface but on a newer rollout track. It exposes 17 endpoints for listing emails, reading and resetting drafts, restoring revisions, creating AB-test variations, and pulling per-email statistics as both list and histogram aggregations. Pick this rollout when the consumer needs the latest shape of these endpoints and the matching schema fields.

## For AI agents

Newer rollout of the HubSpot marketing email endpoints - manage drafts, AB tests, revisions, and statistics on the rollout-155892 build.

## Scope

Does not send transactional one-off emails, manage CRM lists, or handle SMS - use for managing marketing email assets on the V3 rollout only.

## Capabilities

- Read and reset the draft of a marketing email on the V3 rollout
- Restore a prior revision into the draft slot to roll back content changes
- Create an AB-test variation of an email and read it back by source email id
- Pull per-email engagement statistics as either a flat list or a time-bucketed histogram
- List the revisions of a marketing email so an agent can pick a historical version to restore
- Manage the full marketing email asset lifecycle on the latest endpoint rollout

## Use cases

### Latest-Rollout Editorial Automation

Consume the rollout-155892 shape of the marketing email endpoints when your integration depends on the newest field set and behaviour. Read the draft, run content validation, and reset or restore as needed - all on the V3 rollout. Useful when a parallel team is migrating off the older rollout and you need to point your agent at the new payload shape.

Example prompt: Call GET /marketing/v3/emails/{emailId}/draft on the V3 rollout, validate the content, then POST /marketing/v3/emails/{emailId}/draft/reset if validation fails.

### AB Test Setup on the New Rollout

Set up AB tests on the V3 rollout by creating a variation through POST /marketing/v3/emails/ab-test/create-variation and reading it back via the get-variation endpoint. The variation participates in HubSpot's traffic split once published, and the V3 shape carries the latest metadata fields available on test variations.

Example prompt: Call POST /marketing/v3/emails/ab-test/create-variation with the source email id, then GET /marketing/v3/emails/{emailId}/ab-test/get-variation to confirm.

### Trend Reporting via Histogram Statistics

Pull a histogram of opens, clicks, and deliveries bucketed over time using GET /marketing/v3/emails/statistics/histogram on the V3 rollout. The bucketed shape avoids client-side aggregation and matches dashboard rendering libraries directly. Useful for weekly trend digests and exec-facing reports.

Example prompt: Call GET /marketing/v3/emails/statistics/histogram with interval=DAY and a 30-day window, then chart the returned buckets.

### AI Agent Email Recovery via Jentic

An AI agent restoring an email after an accidental edit lists the email's revisions, picks the prior good revision, and restores it into the draft slot. The agent searches Jentic for revision operations, loads the schema for restore-to-draft, and executes the call. Jentic isolates the OAuth token so the agent handles no raw credentials.

Example prompt: Search Jentic for "restore hubspot email revision", load the schema for POST /marketing/v3/emails/{emailId}/revisions/{revisionId}/restore-to-draft, and execute with the chosen revision id.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /marketing/v3/emails/{emailId}/draft | Read the current draft |
| POST | /marketing/v3/emails/{emailId}/draft/reset | Reset the draft to last published |
| POST | /marketing/v3/emails/ab-test/create-variation | Create an AB-test variation |
| GET | /marketing/v3/emails/{emailId}/ab-test/get-variation | Get an AB-test variation by source email id |
| POST | /marketing/v3/emails/{emailId}/revisions/{revisionId}/restore-to-draft | Restore a prior revision into the draft |
| GET | /marketing/v3/emails/{emailId}/revisions | List revisions for an email |
| GET | /marketing/v3/emails/statistics/list | List per-email statistics |
| GET | /marketing/v3/emails/statistics/histogram | Histogram of engagement metrics |

## Key resources

- **Emails** — Marketing email assets on the V3 rollout.
- **Drafts** — In-progress draft of an email separate from the published copy.
- **AB Test Variations** — Variation records for AB-test traffic split.
- **Revisions** — Historical email versions available for restore.
- **Statistics** — Per-email engagement metrics, list and histogram.

## Why Jentic

- **Setup:** Wiring HubSpot Marketing Emails V3 by hand means running its OAuth flow or minting a private-app token, targeting api.hubapi.com, and handling paging and rate limits on statistics calls yourself. Through Jentic you install once, import Marketing Emails V3 from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** This API puts the email id in the URL path (/marketing/v3/emails/{emailId}/...), so a rule can pin your agent to work on one marketing email: it can read that email's drafts, revisions, and A/B variations and nothing else. You choose the operations it may call, so a draft reset or a revision restore is not included unless you add it.
- **Credential handling:** Your HubSpot OAuth or private-app token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'restore a HubSpot email revision' or 'get email A/B test statistics', and Jentic returns the matching V3 operation with its input schema so the agent calls the right endpoint without browsing the HubSpot reference docs.

## Related APIs

- **Marketing Emails** — Older rollout of the same marketing email endpoint surface
- **Marketing Single-send** — Trigger one-off transactional sends of a marketing email
- **Marketing Campaigns** — Attach marketing emails to campaigns for cross-asset attribution
- **SendGrid Mail** — Delivery-first email API outside the HubSpot ecosystem

## FAQ

### What authentication does the Marketing Emails V3 API use?

It accepts HubSpot OAuth 2.0 access tokens or private app tokens, sent as Bearer in the Authorization header. Through Jentic, the token is stored encrypted in your Jentic One instance and injected at execution time.

### How does V3 differ from the older Marketing Emails endpoints?

V3 is the rollout-155892 build of the same endpoint surface - drafts, AB tests, revisions, statistics - with the latest field shape on responses. Pick V3 when you need the newest payload format; the older rollout remains available for parallel migration.

### Can I roll back an email change on the V3 rollout?

Yes. POST /marketing/v3/emails/{emailId}/draft/reset reverts the draft to the last published state, and POST /marketing/v3/emails/{emailId}/revisions/{revisionId}/restore-to-draft brings a specific historical revision into the draft slot.

### What are the rate limits for this API?

Account-level limits are 100 requests per 10 seconds across HubSpot's authenticated APIs, with daily caps that depend on the subscription tier. Cache statistics responses in your dashboard layer to reduce repeat reads.

### How do I create an AB-test variation through Jentic?

Run pip install jentic, search for "create hubspot email ab test variation", load the schema for POST /marketing/v3/emails/ab-test/create-variation, and execute with the source email id. Get started with Jentic One, the self-hosted execution layer.

### Does the V3 rollout support sending one-off transactional emails?

No. For single transactional sends use the Marketing Single-send API. V3 manages the marketing email asset lifecycle - drafts, AB tests, revisions, statistics.

### Can I limit what my agent is allowed to do with the HubSpot Marketing Emails V3 API?

Yes. Because you self-host Jentic One, your own rules decide which operations and credentials your agent may use. Since this API carries the email id in the URL path (/marketing/v3/emails/{emailId}/...), a rule can pin the agent to a single marketing email so it reads only that email's drafts, revisions, and A/B test variations. You also choose the exact operations it may call, so write actions like a draft reset (POST /marketing/v3/emails/{emailId}/draft/reset) or a revision restore (POST /marketing/v3/emails/{emailId}/revisions/{revisionId}/restore-to-draft) stay out of reach unless you grant them.