API Documentation

Reference for the Cohesive outreach API endpoints.

Base URL

https://getcohesiveai.com/api

All endpoints are scoped to a campaign by its ID.

Authentication

All requests must include an API key in the x-api-key header.

x-api-key: your_api_key_here

Typical Workflow

Most integrations follow this pattern to read conversations and take action on them:

1
Fetch your campaigns
Call GET /api/campaigns to list all campaigns and note the id of the campaign you want to work with.
2
Browse the inbox
Use GET /api/{campaignId}/inbox/all or GET /api/{campaignId}/inbox/replies to see sent emails or replies. Each entry includes the leadEmail you will need for the next step.
3
Get the full conversation
Call GET /api/{campaignId}/conversation?leadEmail=... to retrieve the complete email thread. The history array contains every message with fields like id (message ID), statsId, time, and emailBody.
4
Reply or forward
Use the values from the conversation thread to build your payload. For POST /api/{campaignId}/reply, map the message's statsId -> originalEmailStatsId, id -> originalEmailMessageId, and so on. For POST /api/{campaignId}/forward, pass the statsId and id as messageId along with the toEmails you want to forward to.

Campaigns

GET/api/campaigns

Fetch all campaigns. Returns an array of campaign objects.

Response 200 OK

Field	Type	Description
`id`	`string`	Campaign ID
`createdAt`	`number`	Creation timestamp (ms)
`updatedAt`	`number`	Last updated timestamp (ms)
`status`	`CampaignStatus`	Campaign status
`creationStatus`	`string`	Creation workflow status
`name`	`string`	Campaign name

Error Response 4xx / 5xx

Field	Type	Description
`error`	`string`	Error message describing what went wrong

curl -X GET \
  -H "x-api-key: your_api_key_here" \
  "https://getcohesiveai.com/api/campaigns"

Inbox

GET/api/{campaignId}/inbox/all

Fetch all sent emails for a campaign.

Query Parameters

Name	Type	Required	Description
`offset`	`number`	No	Pagination offset
`sortBy`	`string`	No	Sort order for results
`search`	`string`	No	Search filter

Response 200 OK

Field	Type	Description
`leadEmail`	`string`	Lead's email address
`leadName`	`string`	Lead's display name
`category`	`"reply" \| "sent"`	Conversation category
`lastTimestamp`	`number`	Timestamp of the last message (ms)
`isInterested`	`boolean`	Whether the lead is marked as interested
`tagline`	`string`	Short summary of the conversation
`tags`	`string[]`	Tags applied to the conversation

Error Response 4xx / 5xx

Field	Type	Description
`error`	`string`	Error message describing what went wrong

curl -X GET \
  -H "x-api-key: your_api_key_here" \
  "https://getcohesiveai.com/api/{campaignId}/inbox/all?offset=0&sortBy=date&search=acme"

GET/api/{campaignId}/inbox/replies

Fetch all replies for a campaign.

Query Parameters

Name	Type	Required	Description
`offset`	`number`	No	Pagination offset
`sortBy`	`string`	No	Sort order for results
`search`	`string`	No	Search filter
`isInterested`	`string`	No	Filter by interest status ("true" / "false")

Response 200 OK

Field	Type	Description
`leadEmail`	`string`	Lead's email address
`leadName`	`string`	Lead's display name
`category`	`"reply" \| "sent"`	Conversation category
`lastTimestamp`	`number`	Timestamp of the last message (ms)
`isInterested`	`boolean`	Whether the lead is marked as interested
`tagline`	`string`	Short summary of the conversation
`tags`	`string[]`	Tags applied to the conversation

Error Response 4xx / 5xx

Field	Type	Description
`error`	`string`	Error message describing what went wrong

curl -X GET \
  -H "x-api-key: your_api_key_here" \
  "https://getcohesiveai.com/api/{campaignId}/inbox/replies?offset=0&isInterested=true"

GET/api/{campaignId}/conversation

Fetch the full conversation history with a lead.

Query Parameters

Name	Type	Required	Description
`leadEmail`	`string`	Yes	Email address of the lead

Response 200 OK

Field	Type	Description
`fromEmail`	`string`	Sender email address
`toEmail`	`string`	Recipient email address
`history`	`CohesiveCampaignMessage[]`	Array of messages in the conversation

Error Response 4xx / 5xx

Field	Type	Description
`error`	`string`	Error message describing what went wrong

curl -X GET \
  -H "x-api-key: your_api_key_here" \
  "https://getcohesiveai.com/api/{campaignId}/conversation?leadEmail=jane@example.com"

Actions

POST/api/{campaignId}/reply

Send a reply to a conversation.

Request Body (JSON)

Field	Type	Required	Description
`senderEmail`	`string`	Yes	Email address of the sender
`replyEmailBody`	`string`	Yes	HTML body of the reply
`originalEmailStatsId`	`string`	Yes	Stats ID of the original email
`originalEmailMessageId`	`string`	Yes	Message ID of the original email
`originalEmailTime`	`string`	Yes	Timestamp of the original email
`originalEmailBody`	`string`	Yes	Body of the original email
`cc`	`string \| null`	No	CC recipients
`bcc`	`string \| null`	No	BCC recipients
`leadEmail`	`string`	Yes	Lead's email address
`messageId`	`string`	Yes	Message ID for threading
`attachments`	`Attachment[]`	No	Array of { url, filename, contentType }

Response 200 OK

Field	Type	Description
`message`	`string`	Success confirmation message

Error Response 4xx / 5xx

Field	Type	Description
`error`	`string`	Error message describing what went wrong

curl -X POST \
  "https://getcohesiveai.com/api/{campaignId}/reply" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "senderEmail": "you@company.com",
    "replyEmailBody": "<p>Thanks for your interest!</p>",
    "originalEmailStatsId": "stat_123",
    "originalEmailMessageId": "msg_456",
    "originalEmailTime": "2025-01-15T10:30:00Z",
    "originalEmailBody": "<p>Original message</p>",
    "cc": null,
    "bcc": null,
    "leadEmail": "jane@example.com",
    "messageId": "msg_789",
    "attachments": []
  }'

POST/api/{campaignId}/forward

Forward a conversation to other recipients.

Request Body (JSON)

Field	Type	Required	Description
`senderEmail`	`string`	Yes	Email address of the sender
`leadEmail`	`string`	Yes	Lead's email address
`statsId`	`string`	Yes	Stats ID of the email to forward
`cc`	`string \| null`	No	CC recipients
`bcc`	`string \| null`	No	BCC recipients
`toEmails`	`string`	Yes	Comma-separated recipient email addresses
`messageId`	`string`	Yes	Message ID for threading
`attachments`	`Attachment[]`	No	Array of { url, filename, contentType }

Response 200 OK

Field	Type	Description
`message`	`string`	Success confirmation message

Error Response 4xx / 5xx

Field	Type	Description
`error`	`string`	Error message describing what went wrong

curl -X POST \
  "https://getcohesiveai.com/api/{campaignId}/forward" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "senderEmail": "you@company.com",
    "leadEmail": "jane@example.com",
    "statsId": "stat_123",
    "cc": null,
    "bcc": null,
    "toEmails": "team@company.com,manager@company.com",
    "messageId": "msg_789",
    "attachments": []
  }'

Types

CampaignStatus

Enum of possible campaign statuses:

"DRAFTED""ACTIVE""COMPLETED""STOPPED""PAUSED""ARCHIVED"

Attachment

Field	Type	Description
`url`	`string`	URL of the attachment file
`filename`	`string`	Original file name
`contentType`	`string`	MIME type (e.g. "application/pdf")

CohesiveCampaignMessage

Field	Type	Description
`type`	`string`	Message type
`id`	`string`	Unique message identifier
`time`	`string`	Timestamp of the message
`from`	`string`	Sender email address
`to`	`string`	Recipient email address
`emailBody`	`string`	HTML body of the email
`subject`	`string`	Email subject line
`emailSequenceNumber`	`string \| null`	Sequence number in the campaign
`openCount`	`number \| null`	Number of times the email was opened
`clickCount`	`number \| null`	Number of link clicks
`campaignId`	`string`	Associated campaign ID
`statsId`	`string`	Stats tracking ID
`cc`	`string[]`	CC recipients
`bcc`	`string[]`	BCC recipients
`attachments`	`Attachment[]`	File attachments