> ## Documentation Index
> Fetch the complete documentation index at: https://developers.heymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send email messages
> Send email from a Heymarket inbox or reply in an existing email conversation.
Use this endpoint to send email through a connected Heymarket inbox. Start a new conversation with `targets`, or reply in an existing thread with `convo_id`.
The `text` field supports HTML. Include `raw_text` when you want a plain-text fallback for email clients that do not render HTML.
## OpenAPI
````yaml api-reference/openapi/heymarket-openapi-3.1.2.yaml POST /v1/email/send
openapi: 3.1.2
info:
contact:
email: help@heymarket.com
name: API Support
url: https://heymarket.com
description: >
Welcome to Heymarket’s API! Many users access Heymarket via the web app,
mobile apps, or one of the out-of-the-box platform integrations.
However, much of Heymarket’s functionality can also be accessed via the API.
The flexibility and scalability of the API makes it an excellent choice for
integrating Heymarket into existing applications.
This documentation provides details on: available authentication methods,
endpoints that are available and error message information.
If you want to get right to the action, download the collection to start
performing calls from Postman or other similar software.
All valid HTTP request and response bodies are encoded in JSON. For security
purposes API requests must be made over HTTPS. Calls made over plain HTTP or
without authentication will fail.
Base URL: https://api.heymarket.com
# Rate Limit
The Heymarket API has a rate limit of 500 requests per minute. Exceeding the
rate limit will result in responses with a 429 status code.
# Request IDs
Each API request has an associated request identifier. You can find this
value in the response headers, under `X-Request-Id`.
If you need to contact us about a specific request, providing the request
identifier will ensure the fastest possible resolution.
# Webhooks
You can read more about [getting started with
webhooks](https://help.heymarket.com/hc/en-us/articles/4416494130701-Getting-Started-with-Webhooks)
from our articles collection.
# Additional Admin APIs
For more information about additional Admin APIs, please contact us at .
license:
name: Heymarket
url: https://heymarket.com/legal
termsOfService: https://heymarket.com/tos
title: Heymarket API
version: '1.0'
servers:
- url: https://api.heymarket.com
security: []
tags:
- name: Inboxes
description: >
The `Inbox` object represents a read only view of the team's inbox(es) in
Heymarket.
Any API requests that deal with message sending or scheduling will require
an inbox ID as a parameter.
#### The Inbox object
| Attributes |
Description |
| ---------- |
--------------------------------------------------------------------- |
| `id` | Unique identifier for the
object |
| `name` | Name of the
inbox |
| `team` | Unique identifier for your
team |
| `members` | Unique identifier for your team members who have access to
the inbox |
| `phones` | Heymarket phone number(s) associated with the
inbox |
- name: Users
description: >
The `User` object represents a team user in Heymarket.
#### The User object
| Attributes |
Description |
| ------------------ |
------------------------------------------------------------- |
| `id` | Unique identifier for the
object |
| `name` | Name of the
user |
| `email` | Email address of the
user |
| `phone` | Phone number of the
user |
| `role_id` | Unique identifier of the role of the user within
the team |
| `team_id` | Unique identifier for the team the user belongs
to |
| `created_at` | Creation date of the team
user |
| `updated_at` | Last updated date of the team
user |
| `user_created_at` | Creation date of the base
user |
| `user_updated_at` | Last updated date of the base
user |
- name: Team
description: >
The `Team` object represents a read only view of the team in Heymarket.
#### The Team object
| Attributes |
Description |
| ---------- |
--------------------------------------------------------------------- |
| `id` | Unique identifier for the
object |
| `name` | Name of the
team |
| `list_size` | List size limit
| `members` | Unique identifiers for the users who have access to the
team as well as their role within the team|
- name: Contacts
description: >
The `Contact` object is a Heymarket contact. The contacts in Heymarket are
used for storing information such as name, phone number, and email
address. Contacts also store custom fields which can be used for search,
list creation, and merge tokens while sending messages.
#### The Contact object
| Attributes |
Description
|
| ------------------ |
--------------------------------------------------------------------------
|
| `id` | Unique identifier for the
object |
| `display_name` | Display name, usually a combination of first and
last name |
| `first` | First
name |
| `last` | Last
name |
| `email` | Email
address |
| `phone` | Phone
number |
| `custom` | Custom fields with value if present, only lists
contact field ID and value |
| `team_id` | Unique identifier for your Heymarket
team |
| `creator_id` | Unique identifier for the user who created the
contact, same as the member ID returned by Get
Inboxes |
| `shared` | Boolean value for whether the contact is shared
with team members |
| `created` | Creation
date |
| `updated` | Last updated
date |
| `rev` | Last revision
number |
| `op` | Operation
performed |
| `assigned_user_id` | Contact Owner
ID |
| `tags` | Array of up to 5 `tag_id`
objects |
| `is_opted_out` | Is this contact opted out of
messaging? |
- name: Conversations
description: The `Conversation` object represents a messaging thread in Heymarket.
- name: Lists
description: >
The `List` object in Heymarket is used for organizing multiple phone
numbers. You can send a single message to a list, the contacts will never
see each other and can reply privately. Lists are also used as a source of
contacts for your campaigns.
#### The List object
| Attributes | Description |
| ------------ | --------------------------------------------------- |
| `id` | Unique identifier for the object |
| `name` | List name |
| `local_id` | Client provided unique identifier for the object |
| `targets` | Object containing multiple `ListTarget` objects |
| `team_id` | Unique identifier for your Heymarket team |
| `creator_id` | Unique identifier for the user who created the list |
| `shared` | If the list is shared with team
members |
| `created` | Creation date |
| `updated` | Last updated date |
| `rev` | Last revision number |
| `op` | Operation
performed |
The `targets` object is a light weight representation of a contact.
`phone` is used as a key and it has name fields as optional attributes
which will be used as a merge token during message sending if there is no
real Heymarket contact available for this phone number.
#### The ListTarget object
| Attributes | Description |
| ---------- | ----------------------- |
| `f` | First name (if available) |
| `l` | Last name (if available) |
- name: Templates
description: >
The `Template` object in Heymarket is a pre-defined message with text and
media. Templates can also contain merge tokens which will insert the
appropriate custom field values when sending the message. The main body of
the template is stored in the `content` attribute.
#### The Template object
| Attributes | Description |
| ------------ | --------------------------------------------------- |
| `id` | Unique identifier for the object |
| `name` | Template name |
| `local_id` | Client provided unique identifier for the object |
| `content` | Object representing template content |
| `team_id` | Unique identifier for your Heymarket team |
| `creator_id` | Unique identifier for the user who created the template,
same as the member ID returned by Get Inboxes |
| `shared` | If the template is shared with team
members |
| `created` | Creation date |
| `updated` | Last updated date |
| `rev` | Last revision number |
| `op` | Operation
performed |
#### The Content object
| Attributes | Description |
| ---------- | ------------------------------- |
| `text` | Message text |
| `gallery` | Array of `GalleryEntry` objects |
- name: Messages
description: >
The `Messages` API is a powerful Heymarket feature. With it you can send
messages to individual contacts or a list of contacts.
It has all the features of Heymarket's native clients, including sending
messages from a template, sending media, and inserting merge tokens.
- name: Schedule
description: >
With the `Scheduling` API you can schedule a message to be sent to an
individual contact or to a list.
- name: Surveys
description: >
Ask your customers a set of standardized questions to quickly understand
their experience with your company.
- name: Tags
description: |
The `Tag` object in Heymarket.
#### The Tag object
| Attributes | Description |
| ------------ | --------------------------------------------------- |
| `id` | Unique identifier for the object |
| `tag` | Tag name |
| `color` | Color |
| `team_id` | Unique identifier for your Heymarket team |
| `created` | Creation date |
| `updated` | Last updated date |
| `rev` | Last revision number |
- name: Links
description: >
The `Link` object represents a tracked short URL owned by your team.
Link tracking must be enabled for your team to use these endpoints.
Requests from teams without the
link tracking feature return `403` with the message
`link_tracking_not_available`.
All link operations are scoped to the team identified by your API
credentials — links belonging to
other teams cannot be read, updated, or deleted, and lookups for them
return `404`.
#### The Link object
| Attributes | Description |
| ---------- | ----------- |
| `id` | Unique identifier for the object |
| `short_code` | Code segment of the short URL |
| `short_url` | Full short URL to include in messages |
| `original_url` | Destination URL the short link redirects to |
| `team_id` | Unique identifier for your team |
| `target` | Target the link is attributed to (optional) |
| `conversation_id` | Conversation the link is attributed to (optional) |
| `broadcast_id` | Broadcast the link is attributed to (optional) |
| `campaign_step_id` | Campaign step the link is attributed to (optional)
|
| `template_id` | Template the link is attributed to (optional) |
| `last_visited_at` | Timestamp of the most recent click (optional) |
| `created_at` | Creation date |
- name: Webhooks
description: Events Heymarket sends to webhook URLs configured for a team.
paths:
/v1/email/send:
post:
tags:
- Messages
summary: Send Email Message
description: >
Send a 1:1 email message to an individual contact or existing
conversation.
#### Request body attributes
| Attributes | Description |
| --- | --- |
| `creator_id` | **integer (required)**
Unique identifier for the
sender, same as the member ID returned by Get Inboxes. |
| `inbox` | **integer (required)**
Unique identifier for the inbox
from which the email will be sent. |
| `text` | **string (required)**
Email message text body (HTML
supported). |
| `raw_text` | **string (optional)**
Plain text version of the
email message. |
| `local_id` | **string (optional)**
Client unique identifier for
the message. |
| `conv_title` | **string (optional)**
Title for new conversation
if creating one. |
| `targets` | **array (optional)**
Array of email addresses with
`to:` or `cc:` prefixes for new conversations. Each array element can
contain multiple comma-separated emails (e.g.
["to:sample+101@example.com,sample+102@example.com",
"cc:sample+103@example.com,sample+104@example.com"]). |
| `convo_id` | **integer (optional)**
Unique identifier for an
existing conversation to send the email to the same thread. This can be
retrieved from the response of sending the first email. |
#### Example for sending email to existing conversation
```json
{
"text": "Hello from API
",
"inbox": 123,
"creator_id": 1234,
"convo_id": 45362
}
```
#### Example for sending email to new conversation
```json
{
"text": "Hello from API
",
"inbox": 123,
"creator_id": 1234,
"conv_title": "New Message",
"local_id": "f504779b-8547-a3123872f9aa",
"targets": [
"to:sample+101@example.com,sample+102@example.com",
"cc:sample+103@example.com,sample+104@example.com"
],
"convo_id": 45362
}
```
operationId: v1SendEmailMessage
requestBody:
content:
application/json:
schema:
type: object
required:
- creator_id
properties:
creator_id:
type: integer
description: Unique identifier for the sender
inbox:
type: integer
description: Unique identifier for the inbox
text:
type: string
description: Email message text (HTML supported)
raw_text:
type: string
description: Plain text version of the email message
local_id:
type: string
description: Client unique identifier for the message
conv_title:
type: string
description: Title for new conversation if creating one
targets:
type: array
description: >-
Array of email addresses with 'to:' or 'cc:' prefixes for
new conversations. Each array element can contain multiple
comma-separated emails
items:
type: string
convo_id:
type: integer
description: >-
Unique identifier required for an existing conversation to
send the email to the same thread
description: Email message json
required: true
responses:
'200':
description: Email sent successfully
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: Message ID
convo_id:
type: integer
description: Conversation ID
queued:
type: boolean
description: Whether the message was queued
date:
type: string
format: date-time
description: Send date in ISO format
compliance_results:
type: object
description: Compliance check results
'400':
description: bad_data
content:
application/json:
schema:
type: string
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
description: denied
content:
application/json:
schema:
type: string
'429':
$ref: '#/components/responses/TooManyRequestsError'
default:
$ref: '#/components/responses/DefaultServerError'
security:
- ApiSecretJwtAuth: []
- LegacyApiKeyAuth: []
components:
responses:
UnauthorizedError:
description: Authentication credentials were missing or invalid.
content:
text/plain:
schema:
type: string
examples:
response:
value: Unauthorized
TooManyRequestsError:
description: The request exceeded the API rate limit.
content:
text/plain:
schema:
type: string
examples:
response:
value: too many requests
DefaultServerError:
description: Unexpected server error.
content:
text/plain:
schema:
type: string
examples:
response:
value: error
securitySchemes:
ApiSecretJwtAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Recommended authentication for new integrations. Generate a short-lived
JWT from your API Secret ID and API Secret Key, then pass the signed JWT
as a bearer token in the `Authorization` header.
API Secret credentials are available in the Heymarket app under Settings
> Integrations > API. The Secret Key is shown only when it is generated,
so copy and store it securely before closing the dialog.
Use the following JWT values:
```json
{
"alg": "HS256",
"typ": "JWT"
}
```
```text
{
"iss": "YOUR_API_SECRET_ID",
"iat": CURRENT_UNIX_TIMESTAMP
}
```
Replace `CURRENT_UNIX_TIMESTAMP` with the current Unix timestamp in
seconds when generating the token.
Sign the JWT with HMAC-SHA256 using this signing secret:
```text
YOUR_API_SECRET_ID||YOUR_API_SECRET_KEY
```
Send the signed JWT as a bearer token:
```text
Authorization: Bearer YOUR_SIGNED_JWT
```
Tokens expire 5 minutes after the `iat` timestamp. Generate a new JWT
per request, or cache it briefly for less than 5 minutes. Generate JWTs
only from trusted server-side code; do not expose the API Secret Key in
browser, mobile, or other client-side code.
LegacyApiKeyAuth:
type: http
scheme: bearer
bearerFormat: Team API key
description: >-
Legacy authentication for existing integrations. Provide the Heymarket
team API key as a bearer token in the `Authorization` header.
```text
Authorization: Bearer YOUR_API_KEY
```
API key authentication is planned for deprecation. New integrations
should use API Secret JWT authentication.
````