For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
*status* must be one of the following:
- `inbox` to log an already received email.
- `draft` to create a draft email.
- `scheduled` to send an email at a scheduled date and time, which must be specified in the `date_scheduled` field.
- `outbox` to actually **send** an email. To delay email sending by a few seconds (to allow undo), specify `send_in` in seconds (must be less than 60).
- `sent` to log an already sent email.
Only drafts can be modified, and their status can be changed to `scheduled` (to send later) or `outbox` (to send immediately). Scheduled emails, or emails in outbox that weren't sent yet can be canceled by setting the status back to `draft`.
For scheduled, outbox, or sent emails, a `followup_date` may be posted, which will have Close create an email followup task if no response was received.
We'll render an Email Template server-side if you include a `template_id` _without_ including `body_text` or `body_html` in your POST.
To specify both a sender name and a sender email address when posting an email, you can use the `sender` field with the format `"sender": ""John Smith" <emailaddress@example.com>"`
The `sender` field is **required** for emails with status `inbox`, `scheduled`, `outbox`, or `error`. It may be omitted for `draft` (since the sender can be specified later before sending) and `sent` (where it defaults to the email address of the `user` associated with the email or the owner of the API key).
To include an attachment, you must first upload the file to Close using the [Files API](https://developer.close.com/api/resources/files). Then, add an object to the `attachments` array with the following fields: `url`, `filename`, `content_type`, and `size`. The `url` should be the URL provided in the `download.url` field of the response from the [Files API](https://developer.close.com/api/resources/files). It must begin `https://app.close.com/go/file/`.
Authentication
AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
This endpoint expects an object.
lead_idstringRequired
statusenumRequired
activity_atdatetime or nullOptional
attachmentslist of objects or nullOptional
bcclist of strings or nullOptional
body_htmlstring or nullOptional<=1048576 characters
body_textstring or nullOptional<=1048576 characters
cclist of strings or nullOptional
contact_idstring or nullOptional
created_bystring or nullOptional
date_createddatetime or nullOptional
email_account_idstring or nullOptional
followup_datedatetime or nullOptional
followup_sequence_add_cc_bccboolean or nullOptional
followup_sequence_delayinteger or nullOptional>=86400
followup_sequence_idstring or nullOptional
in_reply_to_idstring or nullOptional
openslist of objects or nullOptional
organization_idstring or nullOptional
senderstring or nullOptionalformat: "email"
subjectstring or nullOptional<=1000 characters
template_idstring or nullOptional
tolist of strings or nullOptional
user_idstring or nullOptional
Response
Successful response
_typestring
activity_atdatetime or null
bcclist of strings
body_htmlstring or null
body_textstring or null
bulk_email_action_idstring or null
cclist of strings
contact_idstring or null
created_bystring or null
date_createddatetime
date_scheduleddatetime or null
date_sentdatetime or null
date_updateddatetime
directionenum or null
Direction of communication. Outgoing means the communication flowing from the user to the lead/contact. Inbound means the opposite.
Allowed values:
followup_sequence_add_cc_bccboolean
followup_sequence_delayinteger or null
has_replyboolean
idstring
in_reply_to_idstring or null
lead_idstring or null
message_idslist of strings
need_smtp_credentialsboolean
opens_summarystring or null
organization_idstring
referenceslist of strings
send_as_idstring or null
senderstring or null
statusenum
Status of a message, such as Email or SMS.
subjectstring or null
template_idstring or null
thread_idstring or null
tolist of strings
updated_bystring or null
user_idstring or null
userslist of strings
agent_action_reasonstring or nullOptional
agent_config_idstring or nullOptional
attachmentslist of objects or nullOptional
body_previewstring or nullOptional
created_by_namestring or nullOptional
email_account_idstring or nullOptional
envelopemap from strings to any or nullOptional
followup_sequence_idstring or nullOptional
openslist of objects or nullOptional
send_attemptslist of maps from strings to strings or nullOptional
sequence_idstring or nullOptional
sequence_namestring or nullOptional
sequence_subscription_idstring or nullOptional
template_namestring or nullOptional
updated_by_namestring or nullOptional
user_namestring or nullOptional
Errors
400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
status must be one of the following:
inbox to log an already received email.
draft to create a draft email.
scheduled to send an email at a scheduled date and time, which must be specified in the date_scheduled field.
outbox to actually send an email. To delay email sending by a few seconds (to allow undo), specify send_in in seconds (must be less than 60).
sent to log an already sent email.
Only drafts can be modified, and their status can be changed to scheduled (to send later) or outbox (to send immediately). Scheduled emails, or emails in outbox that weren’t sent yet can be canceled by setting the status back to draft.
For scheduled, outbox, or sent emails, a followup_date may be posted, which will have Close create an email followup task if no response was received.
We’ll render an Email Template server-side if you include a template_idwithout including body_text or body_html in your POST.
To specify both a sender name and a sender email address when posting an email, you can use the sender field with the format "sender": ""John Smith" <emailaddress@example.com>"
The sender field is required for emails with status inbox, scheduled, outbox, or error. It may be omitted for draft (since the sender can be specified later before sending) and sent (where it defaults to the email address of the user associated with the email or the owner of the API key).
To include an attachment, you must first upload the file to Close using the Files API. Then, add an object to the attachments array with the following fields: url, filename, content_type, and size. The url should be the URL provided in the download.url field of the response from the Files API. It must begin https://app.close.com/go/file/.