canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-emails

# HubSpot Emails

The HubSpot Emails CRM API manages email engagement records - logged emails, replies, and email metadata - that appear on contact and deal timelines. It exposes single and batch CRUD plus search across /crm/v3/objects/emails, supporting custom properties, pagination, and association lookups. Use it to log outbound emails sent from external tools, sync inbox replies, or pull engagement history for reporting; it does not send marketing or transactional emails.

## For AI agents

Log, read, search, and batch-manage HubSpot email engagement records on the CRM timeline via /crm/v3/objects/emails.

## Scope

Does not send outbound email, render templates, or run drip campaigns - use for logging and reading email engagement records on the HubSpot CRM timeline only.

## Capabilities

- Log a sent email engagement on a contact's timeline via POST /crm/v3/objects/emails
- Update email metadata such as subject or status with PATCH /crm/v3/objects/emails/{emailId}
- Search email records by direction, status, or owner through POST /crm/v3/objects/emails/search
- Batch-import historical email logs with POST /crm/v3/objects/emails/batch/create
- Upsert emails by external message ID via POST /crm/v3/objects/emails/batch/upsert
- Archive obsolete email records with DELETE /crm/v3/objects/emails/{emailId}

## Use cases

### External Mailbox Sync

Mirror outbound and inbound emails from an external IMAP mailbox or proprietary mailer into HubSpot so reps see complete activity history on the contact and deal timelines. The batch create endpoint handles up to 100 records per call, and upserting by an external message ID prevents duplicates on re-runs of the sync. Pair with the Associations API to attach each email to the right contact.

Example prompt: Batch-upsert 50 historical emails via POST /crm/v3/objects/emails/batch/upsert with idProperty hs_email_message_id, then chain Associations to link each to the matching contact.

### Engagement Reporting

Pull email engagements by date, owner, or direction to power weekly outreach reports - for example, total emails sent by each rep and the count of replies received. The search endpoint accepts complex filterGroups and returns paginated results so reporting jobs can stream large result sets without timing out.

Example prompt: Search HubSpot emails where hs_email_direction equals OUTGOING and hubspot_owner_id equals 200 and createdate is within the last 7 days, returning the count and first page.

### Reply Detection and Routing

Detect when a contact replies to a sales email, then route the reply to the right rep or workflow. The search endpoint can filter by direction INCOMING and a recent threshold timestamp, while a follow-up PATCH can stamp a custom property to mark the reply as processed. This keeps an automated outreach loop honest without bypassing HubSpot.

Example prompt: Search for emails where hs_email_direction equals INCOMING and createdate is within the last hour, then PATCH a custom processed property on each result.

### Agent-Driven Email Logging via Jentic

An AI assistant drafting and sending email from a custom UI logs each send to HubSpot so reps see the activity on the contact timeline without leaving the assistant. Through Jentic the agent searches for the create operation, loads the schema, and executes it with the parsed subject, body, and direction. The flow runs on a single Jentic credential without exposing the HubSpot key.

Example prompt: Use Jentic to search 'log a HubSpot email engagement', load the POST /crm/v3/objects/emails schema, and execute it with hs_email_subject, hs_email_text, and hs_email_direction OUTGOING.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /crm/v3/objects/emails | List email engagements with pagination |
| POST | /crm/v3/objects/emails | Log a new email engagement |
| GET | /crm/v3/objects/emails/{emailId} | Retrieve an email engagement by ID |
| PATCH | /crm/v3/objects/emails/{emailId} | Update an email engagement |
| POST | /crm/v3/objects/emails/batch/upsert | Batch-upsert emails by external ID |
| POST | /crm/v3/objects/emails/search | Search email engagements |

## Key resources

- **Basic** — Single-record CRUD on email engagement objects
- **Batch** — Bulk read, create, update, upsert, and archive across up to 100 emails per request
- **Search** — Filter, sort, and paginate emails by any property

## Why Jentic

- **Setup:** Wiring the HubSpot Emails API by hand means handling its OAuth 2.0 authorization-code flow or a private app token, targeting api.hubapi.com, and building batch and search payloads yourself. Through Jentic you install once, import HubSpot Emails from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** HubSpot gates this API with per-object OAuth scopes, so you grant only the email-engagement scopes your agent needs and you choose which operations it may call: you can allow reading and searching email records while leaving create and update out of the allowed set unless you add them.
- **Credential handling:** Your HubSpot OAuth token 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 'log a HubSpot email engagement' or 'read a logged email', and Jentic returns the matching emails operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Contacts** — Attach logged emails to the contacts they were sent to or received from
- **HubSpot Deals** — Surface logged emails on the deal timeline
- **HubSpot Marketing Email V3** — Send marketing email campaigns rather than logging external messages
- **SendGrid Mail Send** — Send transactional email and log the send back to HubSpot

## FAQ

### What authentication does the HubSpot Emails CRM API use?

The Emails API accepts OAuth 2.0 access tokens with the crm.objects.contacts and engagements scopes plus HubSpot private app API keys passed in the private-app or private-app-legacy header. Through Jentic the credential lives in your Jentic One instance and is injected at execution time so it never enters the agent's context.

### Does this API send emails or just log them?

It only logs and manages engagement records on the CRM timeline - it does not send outbound mail. To send marketing email use HubSpot's Marketing Email API; to send transactional email use a provider like SendGrid and log the result here via POST /crm/v3/objects/emails.

### What are the rate limits for the HubSpot Emails CRM API?

Account-level limits apply - typically 100 requests per 10 seconds for OAuth apps and 190 per 10 seconds for private apps on paid tiers. Use POST /crm/v3/objects/emails/batch/create or batch/upsert when importing historical mail since each batch counts as one request.

### How do I log an email through Jentic?

Run jentic.search('log a HubSpot email engagement'), load the schema for POST /crm/v3/objects/emails, and execute it with hs_email_subject, hs_email_text, hs_email_direction, and hs_timestamp. Jentic returns the created engagement as structured JSON for downstream chaining.

### Can I associate a logged email with a contact and a deal?

Yes, but the association is created via the CRM Associations API after the email engagement is created. Pass the new email's ID and the target contact or deal ID into the associations call - Jentic exposes that as a separate operation you can chain.

### How do I distinguish outbound from inbound emails?

Use the hs_email_direction property - values include OUTGOING, INCOMING, and FORWARD. Filter on this property in POST /crm/v3/objects/emails/search to power direction-specific workflows like reply detection.

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

Yes. Because you run Jentic One yourself, your own rules decide which HubSpot Emails operations and credentials the agent may use, and HubSpot's per-object OAuth scopes let you grant only the email-engagement access it needs. For example, you can allow the agent to read and search records with GET /crm/v3/objects/emails and POST /crm/v3/objects/emails/search while leaving out create and update operations like POST /crm/v3/objects/emails and PATCH /crm/v3/objects/emails/{emailId} unless you add them. Your HubSpot token stays in your Jentic One instance and is injected only for the operations you permit.