API Reference

The reference below covers every endpoint in the Emails API, plus the Communications endpoints for logging off-platform activity. Code examples are generated automatically; the live playground is disabled to prevent accidental writes to production from the docs site.

POST/api/v1/emails

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body for POST /api/v1/emails. One of contactId or contactExternalId is required.

contactId?string

The AgentlyLeads contact ID. Tried first.

contactExternalId?string

The contact's ID in your system. Used when contactId is absent or does not match.

subject*string

Length1 <= length

bodyHtml*string

The HTML body. {{firstName}} is replaced with the recipient's first name at send time.

Length1 <= length

campaign?string

Campaign title to file the draft under. Found or created. When omitted the draft goes into the default outreach campaign.

from?string

The From address. Must be one of GET /api/v1/emails/identities.

offeringId?string

Link the draft (and a newly named campaign) to an offering in this workspace.

contactContext?string

A rolling summary of the relationship, saved on the contact (up to 4,000 characters).

attachments?array<>

Itemsitems <= 10

asUserEmail?string

Act as this workspace member. Defaults to the workspace owner.

Formatemail

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/emails" \  -H "Content-Type: application/json" \  -d '{    "contactExternalId": "hs_contact_123",    "subject": "Buffalo David Bitton men\'s multipacks, 16,300 packs",    "bodyHtml": "<p>Hi {{firstName}},</p><p>We have 16,300 packs available...</p>",    "campaign": "BDB multipacks September",    "from": "kevin@example.com",    "asUserEmail": "kevin@example.com"  }'

{  "email": {    "id": "cmtsv6ts404hzii01dnmu4k5t",    "status": "DRAFT",    "direction": "OUTBOUND",    "subject": "Buffalo David Bitton men's multipacks, 16,300 packs",    "toEmail": "meg@example.com",    "fromEmail": "kevin@example.com",    "contactId": "cmr8dlczc00xkic01prvioybz",    "leadId": null,    "campaignId": "cmtsv6tr704hxii01xyz",    "offeringId": null,    "dealId": null,    "threadId": null,    "error": null,    "sentAt": null,    "createdAt": "2026-09-08T16:16:05.256Z",    "reviewUrl": "https://agentlyleads.com/emails/cmtsv6ts404hzii01dnmu4k5t",    "campaign": {      "id": "string",      "name": "string"    },    "attachmentCount": 0  },  "contact": {    "id": "string",    "name": "string",    "email": "string"  },  "contextSaved": true,  "otherPendingDrafts": [    {      "id": "string",      "subject": "string"    }  ]}

{  "error": "contactId or contactExternalId is required."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:emails."}

{  "error": "Contact not found."}

{  "error": "Rate limit exceeded."}

GET/api/v1/emails

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Query Parameters

status?string

Only emails in this status. Case-insensitive.

Value in

"DRAFT"
"SCHEDULED"
"QUEUED"
"SENT"
"FAILED"

contactId?string

Only emails for this contact.

campaignId?string

Only emails filed under this campaign.

limit?integer

Maximum rows to return. This endpoint does not paginate.

Range1 <= value <= 200

Default50

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/emails"

{  "emails": [    {      "id": "string",      "status": "DRAFT",      "direction": "OUTBOUND",      "subject": "string",      "toEmail": "string",      "fromEmail": "string",      "contact": {        "id": "string",        "name": "string",        "email": "string"      },      "campaign": {        "id": "string",        "name": "string"      },      "dealId": "string",      "opened": true,      "opens": 0,      "clicks": 0,      "replied": true,      "unread": true,      "sentAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "count": 0}

{  "error": "status must be one of DRAFT, SCHEDULED, QUEUED, SENT, FAILED."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:emails."}

{  "error": "Rate limit exceeded."}

GET/api/v1/emails/identities

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Query Parameters

asUserEmail?string

The workspace member to list identities for. Defaults to the workspace owner.

Formatemail

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/emails/identities"

{  "identities": [    {      "address": "Kevin Lee <kevin@example.com>",      "email": "kevin@example.com",      "default": true    }  ],  "default": "Kevin Lee <kevin@example.com>"}

{  "error": "asUserEmail \"someone@example.com\" is not a member of this workspace."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:emails."}

{  "error": "Rate limit exceeded."}

GET/api/v1/emails/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The email ID.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/emails/string"

{  "email": {    "id": "cmtsv6ts404hzii01dnmu4k5t",    "status": "DRAFT",    "direction": "OUTBOUND",    "subject": "Buffalo David Bitton men's multipacks, 16,300 packs",    "toEmail": "meg@example.com",    "fromEmail": "kevin@example.com",    "contactId": "cmr8dlczc00xkic01prvioybz",    "leadId": null,    "campaignId": "cmtsv6tr704hxii01xyz",    "offeringId": null,    "dealId": null,    "threadId": null,    "error": null,    "sentAt": null,    "createdAt": "2026-09-08T16:16:05.256Z",    "reviewUrl": "https://agentlyleads.com/emails/cmtsv6ts404hzii01dnmu4k5t",    "bodyHtml": "string",    "campaign": {      "id": "string",      "name": "string"    },    "contact": {      "id": "string",      "name": "string",      "email": "string",      "externalId": "string"    }  },  "attachments": [    {      "id": "string",      "fileName": "string",      "contentType": "string",      "size": 0,      "source": "email",      "campaignId": "string"    }  ],  "thread": [    {      "id": "cmtsv6ts404hzii01dnmu4k5t",      "status": "DRAFT",      "direction": "OUTBOUND",      "subject": "Buffalo David Bitton men's multipacks, 16,300 packs",      "toEmail": "meg@example.com",      "fromEmail": "kevin@example.com",      "contactId": "cmr8dlczc00xkic01prvioybz",      "leadId": null,      "campaignId": "cmtsv6tr704hxii01xyz",      "offeringId": null,      "dealId": null,      "threadId": null,      "error": null,      "sentAt": null,      "createdAt": "2026-09-08T16:16:05.256Z",      "reviewUrl": "https://agentlyleads.com/emails/cmtsv6ts404hzii01dnmu4k5t"    }  ],  "engagement": {    "opened": true,    "opens": 0,    "machineOpens": 0,    "firstOpenAt": "2019-08-24T14:15:22Z",    "lastOpenAt": "2019-08-24T14:15:22Z",    "clicks": 0,    "delivered": true,    "bounced": true,    "timeline": [      {        "at": "2019-08-24T14:15:22Z",        "type": "OPEN",        "client": "GMAIL",        "source": "PERSON",        "url": "string"      }    ]  }}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:emails."}

{  "error": "Email not found."}

{  "error": "Rate limit exceeded."}

PATCH/api/v1/emails/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The email ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

subject?string

Length1 <= length

bodyHtml?string

Replaces the old body entirely.

Length1 <= length

from?string

Must be one of GET /api/v1/emails/identities.

Length1 <= length

campaign?string

Campaign title to file the draft under. If it matches the current campaign the draft stays put; otherwise the campaign is found or created.

asUserEmail?string

Act as this workspace member. Defaults to the workspace owner.

Formatemail

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/emails/string" \  -H "Content-Type: application/json" \  -d '{    "subject": "Pickleball sets, 15,830 sets, $5.00",    "bodyHtml": "<p>...</p>"  }'

{  "email": {    "id": "cmtsv6ts404hzii01dnmu4k5t",    "status": "DRAFT",    "direction": "OUTBOUND",    "subject": "Buffalo David Bitton men's multipacks, 16,300 packs",    "toEmail": "meg@example.com",    "fromEmail": "kevin@example.com",    "contactId": "cmr8dlczc00xkic01prvioybz",    "leadId": null,    "campaignId": "cmtsv6tr704hxii01xyz",    "offeringId": null,    "dealId": null,    "threadId": null,    "error": null,    "sentAt": null,    "createdAt": "2026-09-08T16:16:05.256Z",    "reviewUrl": "https://agentlyleads.com/emails/cmtsv6ts404hzii01dnmu4k5t"  }}

{  "error": "Nothing to update: pass at least one of subject, bodyHtml, from, campaign."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:emails."}

{  "error": "Draft not found."}

{  "error": "Rate limit exceeded."}

DELETE/api/v1/emails/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The email ID.

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/emails/string"

{  "deleted": 1,  "id": "cmtsv6ts404hzii01dnmu4k5t"}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:emails."}

{  "error": "Email not found."}

{  "error": "Only DRAFT emails can be deleted; sent mail is immutable history."}

{  "error": "Rate limit exceeded."}

POST/api/v1/emails/{id}/reply

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The ID of the email being replied to.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

bodyHtml*string

Length1 <= length

contactContext?string

A rolling summary of the relationship, saved on the contact.

asUserEmail?string

Act as this workspace member. Defaults to the workspace owner.

Formatemail

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/emails/string/reply" \  -H "Content-Type: application/json" \  -d '{    "bodyHtml": "<p>Thanks Meg, sending the line sheet now.</p>"  }'

{  "email": {    "id": "cmtsv6ts404hzii01dnmu4k5t",    "status": "DRAFT",    "direction": "OUTBOUND",    "subject": "Buffalo David Bitton men's multipacks, 16,300 packs",    "toEmail": "meg@example.com",    "fromEmail": "kevin@example.com",    "contactId": "cmr8dlczc00xkic01prvioybz",    "leadId": null,    "campaignId": "cmtsv6tr704hxii01xyz",    "offeringId": null,    "dealId": null,    "threadId": null,    "error": null,    "sentAt": null,    "createdAt": "2026-09-08T16:16:05.256Z",    "reviewUrl": "https://agentlyleads.com/emails/cmtsv6ts404hzii01dnmu4k5t",    "inReplyTo": "string"  },  "contact": {    "id": "string",    "name": "string",    "email": "string"  },  "contextSaved": true}

{  "error": "That email has no linked contact to reply to."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:emails."}

{  "error": "Email not found."}

{  "error": "Rate limit exceeded."}

POST/api/v1/emails/{id}/send

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The draft's ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

asUserEmail?string

Whose connected mailbox transmits when the draft has no explicit From. Defaults to the workspace owner.

Formatemail

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/emails/string/send" \  -H "Content-Type: application/json" \  -d '{    "asUserEmail": "kevin@example.com"  }'

{  "email": {    "id": "cmtsv6ts404hzii01dnmu4k5t",    "status": "DRAFT",    "direction": "OUTBOUND",    "subject": "Buffalo David Bitton men's multipacks, 16,300 packs",    "toEmail": "meg@example.com",    "fromEmail": "kevin@example.com",    "contactId": "cmr8dlczc00xkic01prvioybz",    "leadId": null,    "campaignId": "cmtsv6tr704hxii01xyz",    "offeringId": null,    "dealId": null,    "threadId": null,    "error": null,    "sentAt": null,    "createdAt": "2026-09-08T16:16:05.256Z",    "reviewUrl": "https://agentlyleads.com/emails/cmtsv6ts404hzii01dnmu4k5t"  },  "sent": true}

{  "error": "products must not be empty."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: send:emails."}

{  "error": "Email not found."}

{  "error": "Email is SENT, not a DRAFT."}

{  "error": "Rate limit exceeded."}

{  "email": {    "id": "cmtsv6ts404hzii01dnmu4k5t",    "status": "DRAFT",    "direction": "OUTBOUND",    "subject": "Buffalo David Bitton men's multipacks, 16,300 packs",    "toEmail": "meg@example.com",    "fromEmail": "kevin@example.com",    "contactId": "cmr8dlczc00xkic01prvioybz",    "leadId": null,    "campaignId": "cmtsv6tr704hxii01xyz",    "offeringId": null,    "dealId": null,    "threadId": null,    "error": null,    "sentAt": null,    "createdAt": "2026-09-08T16:16:05.256Z",    "reviewUrl": "https://agentlyleads.com/emails/cmtsv6ts404hzii01dnmu4k5t"  },  "sent": false}

POST/api/v1/communications

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body for POST /api/v1/communications. One of contactId or contactExternalId is required.

contactId?string

contactExternalId?string

type*string

Value in

"CALL"
"EMAIL"
"NOTE"
"MEETING"
"LINKEDIN"

direction?string

Value in

"INBOUND"
"OUTBOUND"

subject?string

body*string

Length1 <= length

occurredAt?string

ISO 8601 with an offset. Defaults to now. Backdate to keep the timeline honest.

Formatdate-time

offeringId?string

Link the entry to an offering in this workspace.

asUserEmail?string

Record it as logged by this workspace member. Defaults to the workspace owner.

Formatemail

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/communications" \  -H "Content-Type: application/json" \  -d '{    "contactExternalId": "hs_contact_123",    "type": "LINKEDIN",    "direction": "INBOUND",    "subject": "Accepted the InMail, asked for toys",    "body": "Hi Howard, TJX buys from new inventory sources every week...",    "occurredAt": "2026-08-16T14:36:00-04:00"  }'

{  "communication": {    "id": "cmtluhfc00w8hig01xiceouo7",    "contactId": "cmr8dlczc00xkic01prvioybz",    "type": "LINKEDIN",    "direction": "INBOUND",    "subject": "Accepted the InMail, asked for toys",    "occurredAt": "2026-08-16T18:36:00.000Z"  }}

{  "error": "body is required."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:communications."}

{  "error": "Contact not found."}

{  "error": "Rate limit exceeded."}

GET/api/v1/communications

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Query Parameters

contactId?string

Only entries for this contact.

contactExternalId?string

Only entries for the contact with this external ID.

type?string

Only entries of this type. Case-insensitive.

Value in

"CALL"
"EMAIL"
"NOTE"
"MEETING"
"LINKEDIN"

updatedSince?string

Only entries that occurred at or after this ISO 8601 datetime.

Formatdate-time

limit?integer

Page size.

Range1 <= value <= 1000

Default100

cursor?string

The nextCursor value from the previous page.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/communications"

{  "communications": [    {      "id": "cmtluhfc00w8hig01xiceouo7",      "type": "LINKEDIN",      "direction": "INBOUND",      "subject": "Accepted the InMail, asked for toys",      "body": "string",      "occurredAt": "2026-08-16T18:36:00.000Z",      "contact": {        "id": "string",        "name": "string",        "externalId": "string"      },      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "nextCursor": "string"}

{  "error": "type must be one of CALL, EMAIL, NOTE, MEETING, LINKEDIN."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:communications."}

{  "error": "Rate limit exceeded."}

API Reference

201application/json

400application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

429application/json

200application/json

400application/json

401application/json

403application/json

429application/json

200application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

200application/json

401application/json

403application/json

404application/json

409application/json

429application/json

201application/json

400application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

502application/json

201application/json

400application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`