openapi: 3.1.0
info:
title: Apollo API — Emailer Messages
summary: Programmatic access to Apollo's sales intelligence and engagement platform — data enrichment, prospect and company
search, and go-to-market workflow management.
description: 'The Apollo API provides programmatic access to [Apollo](https://www.apollo.io/), the all-in-one sales intelligence
and engagement platform. Use it to enrich people and company data (individually or in bulk), search Apollo''s database
of over 240 million contacts and 30 million companies, and manage accounts, contacts, deals, sequences, tasks, calls,
and conversations in your go-to-market workflows.
## Base URL
All API requests are made to `https://api.apollo.io/api/v1`.
## Authentication
- **Apollo users** authenticate with an API key passed in the `x-api-key` request header. See [Create API Keys](https://docs.apollo.io/docs/create-api-key).
- **Apollo partners** building integrations on behalf of mutual users authenticate with the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).
## Rate limits & credits
Rate limits and credit consumption depend on your [Apollo pricing plan](https://docs.apollo.io/docs/api-pricing). Check
your current limits and usage with the [View API Usage Stats and Rate Limits](https://docs.apollo.io/reference/view-api-usage-stats)
endpoint. For more details, see [Rate Limits](https://docs.apollo.io/reference/rate-limits) and the [API FAQs](https://docs.apollo.io/docs/apollo-api-faqs).
New to the API? Start with the [Apollo API overview](https://docs.apollo.io/reference/apollo-api).'
termsOfService: https://www.apollo.io/terms/api
contact:
name: Apollo API Support
url: https://docs.apollo.io/
version: '1.0'
servers:
- url: https://api.apollo.io/api/v1
tags:
- name: Emailer Messages
security:
- apiKey: []
- bearerAuth: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: '[Recommended] API key, passed in the `x-api-key` request header.
See [Create API Keys](https://docs.apollo.io/docs/create-api-key).'
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'OAuth 2.0 access token, used by Apollo partners building integrations.
See the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).'
paths:
/emailer_messages:
post:
summary: Create an Email Draft
description: '## Endpoint essentials
**API key access:** `api/v1/emailer_messages/create` or `Master API key`
**OAuth scopes:** `emailer_messages_create`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
Use the Create an Email Draft endpoint to create a single, unsent email message (an email draft) for a contact. The
draft is created with a `drafted` status — this endpoint doesn''t send the email.<br><br>To send the draft after creating
it, call the <a href="https://docs.apollo.io/reference/send-email-now">Send Email Now endpoint</a> with the `id` returned
in the response.<br><br>You must provide a `contact_id` so Apollo knows who the email is for. Alternatively, to draft
a reply within an existing email thread, provide `in_response_to_emailer_message_id` instead and Apollo infers the
contact and recipients from the parent message.<br><br>The email is drafted from the user that owns the API key. That
user must have permission to email the contact (like by owning the contact or its account), and the contact must not
be blocked by any do not contact settings.<br><br>This endpoint returns the created `emailer_message` object. If the
draft is linked to an outreach task, a `task` object is also returned.'
tags:
- Emailer Messages
operationId: create-an-email-draft
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- contact_id
properties:
contact_id:
type: string
description: 'The Apollo ID for the contact that will receive the email. <br><br>This is required unless
you provide `in_response_to_emailer_message_id`, in which case the contact is inferred from the parent
message. <br><br>To find contact IDs, call the <a href="https://docs.apollo.io/reference/search-for-contacts"
target="_blank">Search for Contacts endpoint</a> and identify the `id` value for the contact. <br><br>Example:
`66e34b81740c50074e3d1bd4`'
subject:
type: string
description: 'The subject line of the email. <br><br>Example: `Quick question about your team''s workflow`'
body_html:
type: string
description: 'The body of the email as HTML. The content is sanitized by Apollo before it is saved. <br><br>Example:
`<p>Hi there, I wanted to reach out about...</p>`'
recipients:
type: array
description: The list of recipients for the email. Use this to set the `to`, `cc`, and `bcc` recipients.
If you do not provide a `to` recipient, Apollo keeps the existing `to` recipients (if any). <br><br>All
recipient emails must be valid, otherwise the request fails and the email is not saved.
items:
type: object
properties:
email:
type: string
description: 'The email address of the recipient. <br><br>Example: `ava.ruiz@sumware.com`'
contact_id:
type: string
description: 'The Apollo ID for the contact associated with this recipient. <br><br>Example: `66e34b81740c50074e3d1bd4`'
recipient_type_cd:
type: string
description: The type of recipient. <ul> <li> `to` </li> <li> `cc` </li> <li> `bcc` </li> </ul>
in_response_to_emailer_message_id:
type: string
description: 'The Apollo ID of an existing email message that this draft is replying to. When provided,
Apollo infers the contact and builds the recipients from the parent message, so you do not need to provide
`contact_id`. <br><br>Example: `66e8cc45028aed019c25d724`'
emailer_template_id:
type: string
description: 'The Apollo ID of an email template to associate with the draft. <br><br>Example: `66e8cc45028aed019c25d725`'
attachment_ids:
type: array
items:
type: string
description: The Apollo IDs of the attachments to include with the email.
enable_tracking:
type: boolean
description: 'Set to `true` to enable open and click tracking for the email. This is only applied if your
team is permitted to track emails. <br><br>Example: `true`'
outreach_task_id:
type: string
description: 'The Apollo ID of an outreach task to associate with the draft. If a drafted email already
exists for this task, Apollo links to that draft instead of creating a new one. <br><br>Example: `66e8cc45028aed019c25d726`'
examples:
Create an email draft for a contact:
value:
contact_id: 66e34b81740c50074e3d1bd4
subject: Quick question about your team's workflow
body_html: <p>Hi Ava, I wanted to reach out about how Apollo can help your team.</p>
recipients:
- email: ava.ruiz@sumware.com
contact_id: 66e34b81740c50074e3d1bd4
recipient_type_cd: to
enable_tracking: true
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
emailer_message:
type: object
properties:
id:
type: string
example: 66e8cc45028aed019c25d724
user_id:
type: string
example: 66a3d80d4238fe02d2baaaaf
status:
type: string
example: drafted
time_zone: {}
provider_message_id: {}
to_name:
type: string
example: Ava Ruiz
due_at: {}
completed_at: {}
emailer_touch_id: {}
emailer_campaign_id: {}
emailer_step_id: {}
failed_at: {}
failure_reason: {}
attachment_ids:
type: array
enable_tracking:
type: boolean
example: true
type:
type: string
example: outreach_manual_email
contact_id:
type: string
example: 66e34b81740c50074e3d1bd4
provider_thread_id: {}
schedule_delayed_reason: {}
demoed: {}
email_account_id:
type: string
example: 66e8c4567f32a501b2605004
due_at_manually_changed: {}
not_sent_reason: {}
bounce: {}
spam_blocked: {}
tracking_disabled_reason: {}
created_at:
type: string
example: '2025-02-03T15:30:00.000Z'
async_sending: {}
due_at_source: {}
crm_id: {}
replied: {}
needs_dynamic_assemble: {}
personalized_opener: {}
reply_class: {}
schedule_delayed_limit_reason: {}
schedule_delayed_reason_details: {}
sensitive_info_redacted: {}
account_id:
type: string
example: 612f9d6cd26c290001d9bda0
conversation_id: {}
click_tracking_enabled:
type: boolean
example: true
open_tracking_enabled:
type: boolean
example: true
ai_variables_status: {}
recipients:
type: array
items:
type: object
properties:
email:
type: string
example: ava.ruiz@sumware.com
raw_name:
type: string
example: Ava Ruiz
recipient_type_cd:
type: string
example: to
contact_id:
type: string
example: 66e34b81740c50074e3d1bd4
user_id: {}
send_from:
type: object
properties:
email:
type: string
example: someemail@apollo.io
raw_name: {}
recipient_type_cd: {}
contact_id: {}
user_id:
type: string
example: 66a3d80d4238fe02d2baaaaf
from_email:
type: string
example: someemail@apollo.io
to_email:
type: string
example: ava.ruiz@sumware.com
from_name: {}
bcc_emails:
type: array
cc_emails:
type: array
send_from_info:
type: string
example: 66e8c4567f32a501b2605004***someemail@apollo.io
body_text:
type: string
example: Hi Ava, I wanted to reach out about how Apollo can help your team.
body_html:
type: string
example: <p>Hi Ava, I wanted to reach out about how Apollo can help your team.</p>
body_html_loaded:
type: boolean
example: true
subject:
type: string
example: Quick question about your team's workflow
contact:
type: object
properties:
id:
type: string
example: 66e34b81740c50074e3d1bd4
first_name:
type: string
example: Ava
last_name:
type: string
example: Ruiz
name:
type: string
example: Ava Ruiz
email:
type: string
example: ava.ruiz@sumware.com
title:
type: string
example: Founder & CEO
organization_name:
type: string
example: Sumware Software
account_id:
type: string
example: 612f9d6cd26c290001d9bda0
owner_id:
type: string
example: 66302798d03b9601c7934ebf
email_status:
type: string
example: verified
task:
type: object
description: The outreach task linked to this email message. Only returned when the message is associated
with an outreach task (for example, when `outreach_task_id` is provided). <br><br>A condensed set of fields
is shown below. For the full task object and all available fields, see the <a href="https://docs.apollo.io/reference/search-tasks"
target="_blank">Search for Tasks endpoint</a>.
properties:
id:
type: string
example: 66e8cc45028aed019c25d724
user_id:
type: string
example: 66a3d80d4238fe02d2baaaaf
status:
type: string
example: scheduled
type:
type: string
example: action_item
priority:
type: string
example: medium
due_at:
type: string
example: '2024-09-21T00:00:00.000+00:00'
completed_at: {}
title:
type: string
example: Reminder - Schedule Demo Call
subject: {}
contact_id:
type: string
example: 66e34b81740c50074e3d1bd4
account_id: {}
opportunity_id: {}
emailer_campaign_id: {}
created_at:
type: string
example: '2024-09-17T00:24:37.436Z'
examples:
Result:
value:
emailer_message:
id: 66e8cc45028aed019c25d724
user_id: 66a3d80d4238fe02d2baaaaf
status: drafted
to_name: Ava Ruiz
due_at: null
completed_at: null
emailer_campaign_id: null
attachment_ids: []
enable_tracking: true
type: outreach_manual_email
contact_id: 66e34b81740c50074e3d1bd4
email_account_id: 66e8c4567f32a501b2605004
created_at: '2025-02-03T15:30:00.000Z'
account_id: 612f9d6cd26c290001d9bda0
click_tracking_enabled: true
open_tracking_enabled: true
recipients:
- email: ava.ruiz@sumware.com
raw_name: Ava Ruiz
recipient_type_cd: to
contact_id: 66e34b81740c50074e3d1bd4
send_from:
email: someemail@apollo.io
user_id: 66a3d80d4238fe02d2baaaaf
from_email: someemail@apollo.io
to_email: ava.ruiz@sumware.com
bcc_emails: []
cc_emails: []
send_from_info: 66e8c4567f32a501b2605004***someemail@apollo.io
body_text: Hi Ava, I wanted to reach out about how Apollo can help your team.
body_html: <p>Hi Ava, I wanted to reach out about how Apollo can help your team.</p>
body_html_loaded: true
subject: Quick question about your team's workflow
contact:
id: 66e34b81740c50074e3d1bd4
first_name: Ava
last_name: Ruiz
name: Ava Ruiz
email: ava.ruiz@sumware.com
title: Founder & CEO
organization_name: Sumware Software
account_id: 612f9d6cd26c290001d9bda0
owner_id: 66302798d03b9601c7934ebf
email_status: verified
'401':
description: '401'
content:
text/plain:
examples:
Check API key:
value: Invalid API key. See https://docs.apollo.io/reference/authentication for how to authenticate.
'422':
description: '422'
content:
application/json:
examples:
Contact does not exist:
value: "{\n \"error\": \"Contact does not exist\"\n}"
No permission to email contact:
value: "{\n \"error\": \"You do not have permission to email Ava Ruiz. You are not the owner of this contact\
\ or account.\"\n}"
Blocked by DNC enforcement:
value: "{\n \"error\": \"Cannot be emailed under your team's DNC enforcement settings\",\n \"error_code\"\
: \"DNC_ENFORCEMENT_BLOCKED\"\n}"
Invalid recipient emails:
value: "{\n \"error\": \"ERROR! Email is NOT SAVED. Invalid recipient emails: [\\\"person@\\\"]\"\n}"
schema:
type: object
properties:
error:
type: string
error_code:
type: string
'429':
description: '429'
content:
application/json:
examples:
Too many requests:
value: "{\n \"message\": \"The maximum number of api calls allowed for api/v1/emailer_messages/create is\
\ 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.\"\n\
}"
schema:
type: object
properties:
message:
type: string
example: The maximum number of api calls allowed for api/v1/emailer_messages/create is 600 times per hour.
Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.
deprecated: false
/emailer_messages/{id}/send_now:
post:
summary: Send Email Now
description: '## Endpoint essentials
**API key access:** `api/v1/emailer_messages/send_now` or `Master API key`
**OAuth scopes:** `emailer_messages_send_now`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
Use the Send Email Now endpoint to immediately send an existing email message.This works for emails that are currently
in a `drafted`, `scheduled`, or `failed` state. Apollo schedules the email to be sent right away and processes it
asynchronously. <br><br>To first create an email draft, use the <a href="https://docs.apollo.io/reference/create-an-email-draft">Create
an Email Draft</a> endpoint and pass the returned `id` to this endpoint. <br><br>The email is sent from the user that
owns the API key. That user must have a linked email account on the message, must have permission to send from that
email account, and must have permission to email the contact. The contact must also not be blocked by any do not contact
settings, and the user must not have exceeded their daily email sending limit. <br><br>Because sending is processed
asynchronously, a successful `200` response means the email has been queued for sending — not that it''s been delivered.
To check whether the email was delivered, poll the <a href="https://docs.apollo.io/reference/check-email-send-status">Check
Email Send Status</a> endpoint using the message `id`.<br><br>This endpoint returns the `emailer_message` object.
If the message is linked to an outreach task, a `task` object is also returned.'
tags:
- Emailer Messages
operationId: send-email-now
parameters:
- name: id
in: path
required: true
description: 'The Apollo ID of the email message to send. This is the `id` returned when you create an email draft.
<br><br>Example: `66e8cc45028aed019c25d724`'
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
surface:
type: string
description: 'Optional. The surface within Apollo that the send is initiated from. Used for internal attribution
and analytics. <br><br>Example: `emails`'
examples:
Send an existing email immediately:
value:
surface: emails
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
emailer_message:
type: object
properties:
id:
type: string
example: 66e8cc45028aed019c25d724
user_id:
type: string
example: 66a3d80d4238fe02d2baaaaf
status:
type: string
example: scheduled
to_name:
type: string
example: Ava Ruiz
due_at:
type: string
example: '2025-02-03T15:30:00.000+00:00'
completed_at: {}
emailer_campaign_id: {}
attachment_ids:
type: array
enable_tracking:
type: boolean
example: true
type:
type: string
example: outreach_manual_email
contact_id:
type: string
example: 66e34b81740c50074e3d1bd4
email_account_id:
type: string
example: 66e8c4567f32a501b2605004
due_at_manually_changed:
type: boolean
example: true
due_at_source:
type: string
example: Email was sent using Send Now action
async_sending:
type: boolean
example: true
created_at:
type: string
example: '2025-02-03T15:30:00.000Z'
account_id:
type: string
example: 612f9d6cd26c290001d9bda0
click_tracking_enabled:
type: boolean
example: true
open_tracking_enabled:
type: boolean
example: true
recipients:
type: array
items:
type: object
properties:
email:
type: string
example: ava.ruiz@sumware.com
raw_name:
type: string
example: Ava Ruiz
recipient_type_cd:
type: string
example: to
contact_id:
type: string
example: 66e34b81740c50074e3d1bd4
user_id: {}
send_from:
type: object
properties:
email:
type: string
example: someemail@apollo.io
raw_name: {}
recipient_type_cd: {}
contact_id: {}
user_id:
type: string
example: 66a3d80d4238fe02d2baaaaf
from_email:
type: string
example: someemail@apollo.io
to_email:
type: string
example: ava.ruiz@sumware.com
from_name: {}
bcc_emails:
type: array
cc_emails:
type: array
send_from_info:
type: string
example: 66e8c4567f32a501b2605004***someemail@apollo.io
body_text:
type: string
example: Hi Ava, I wanted to reach out about how Apollo can help your team.
body_html:
type: string
example: <p>Hi Ava, I wanted to reach out about how Apollo can help your team.</p>
body_html_loaded:
type: boolean
example: true
subject:
type: string
example: Quick question about your team's workflow
contact:
type: object
properties:
id:
type: string
example: 66e34b81740c50074e3d1bd4
first_name:
type: string
example: Ava
last_name:
type: string
example: Ruiz
name:
type: string
example: Ava Ruiz
email:
type: string
example: ava.ruiz@sumware.com
title:
type: string
example: Founder & CEO
organization_name:
type: string
example: Sumware Software
account_id:
type: string
example: 612f9d6cd26c290001d9bda0
owner_id:
type: string
example: 66302798d03b9601c7934ebf
email_status:
type: string
example: verified
task:
type: object
description: The outreach task linked to this email message. Only returned when the message is associated
with an outreach task (for example, when `outreach_task_id` is provided). <br><br>A condensed set of fields
is shown below. For the full task object and all available fields, see the <a href="https://docs.apollo.io/reference/search-tasks"
target="_blank">Search for Tasks endpoint</a>.
properties:
id:
type: string
example: 66e8cc45028aed019c25d724
user_id:
type: string
example: 66a3d80d4238fe02d2baaaaf
status:
type: string
example: scheduled
type:
type: string
example: action_item
priority:
type: string
example: medium
due_at:
type: string
example: '2024-09-21T00:00:00.000+00:00'
completed_at: {}
title:
type: string
example: Reminder - Schedule Demo Call
subject: {}
contact_id:
type: string
example: 66e34b81740c50074e3d1bd4
account_id: {}
opportunity_id: {}
emailer_campaign_id: {}
created_at:
type: string
example: '2024-09-17T00:24:37.436Z'
examples:
Result:
value:
emailer_message:
id: 66e8cc45028aed019c25d724
user_id: 66a3d80d4238fe02d2baaaaf
status: scheduled
to_name: Ava Ruiz
due_at: '2025-02-03T15:30:00.000+00:00'
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-api-documentation/refs/heads/main/openapi/apollo-api-documentation-emailer-messages-api-openapi.yml