Conversation API

Interfaces to manage conversations and messages

Conversations represent email, LinkedIn, or Twitter message threads. You can retrieve conversations, send messages (including email replies from your campaign mailboxes), and manage read/unread status.

ℹ️

V2 API Available

V2 provides standardized responses for conversation endpoints and supports sending messages across all platforms (email, LinkedIn, and Twitter).

List Conversations

Get conversations with filtering and pagination.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/conversations?limit=20' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": [ { "object": "conversation", "id": "conversation-uuid", "platform_type": "linkedin", "title": "John Smith", "last_activity_at": "2025-11-27T10:30:00Z", "is_unread": true, "is_archived": false, "unread_count": 0, "identity": { "id": "identity-uuid", "handle": "my-linkedin-handle", "first_name": "My", "last_name": "Name", "photo": "https://...", "type": "linkedin" }, "participants": [], "last_message": { "text": "Thanks for reaching out!", "timestamp": "2025-11-27T10:30:00Z" }, "team_id": "team-uuid", "created_at": "2025-11-01T00:00:00Z", "updated_at": "2025-11-27T10:30:00Z" } ], "pagination": { "total": 150, "limit": 20, "offset": 0, "hasMore": true }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Query Parameters:

Parameter	Type	Description
`identity_id`	string	Filter by identity
`team_id`	string	Filter by team
`status`	string	`archived` or `unarchived`
`read_status`	string	`read` or `unread`
`search`	string	Search in conversation
`sort_by`	string	Sort field (default: `date`)
`sort_direction`	string	`asc` or `desc`
`limit`	number	Results per page (max: 100)
`offset`	number	Pagination offset

V1 API

bash

curl -X GET 'https://api.supersend.io/v1/conversation/latest-by-profile?TeamId=xxx&limit=20&channel=email' \
  -H "Authorization: Bearer YOUR_API_KEY"# Response
{
  "success": true,
  "data": {
    "conversations": [...],
    "pagination": {...}
  }
}

Get Conversation

Get a specific conversation.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/conversations/conversation-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": { "object": "conversation", "id": "conversation-uuid", "platform_type": "linkedin", "title": "John Smith", "last_activity_at": "2025-11-27T10:30:00Z", "is_unread": false, "is_archived": false, "identity": { "id": "identity-uuid", "handle": "my-linkedin-handle", "first_name": "My", "last_name": "Name", "photo": "https://...", "type": "linkedin" }, "participants": [ { "id": "profile-uuid", "display_name": "John Smith", "avatar_url": "https://...", "username": "johnsmith", "is_self": false } ], "messages": [ { "id": "message-uuid", "text": "Hi John, thanks for your interest...", "timestamp": "2025-11-27T10:00:00Z", "is_from_self": true, "is_read": true, "author": { "id": "profile-uuid", "display_name": "My Name", "avatar_url": "https://...", "username": "my-linkedin-handle" } }, { "id": "message-uuid-2", "text": "That sounds great! Let's schedule a call.", "timestamp": "2025-11-27T10:30:00Z", "is_from_self": false, "is_read": true, "author": { "id": "profile-uuid-2", "display_name": "John Smith", "avatar_url": "https://...", "username": "johnsmith" } } ], "team_id": "team-uuid", "created_at": "2025-11-01T00:00:00Z", "updated_at": "2025-11-27T10:30:00Z" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

Note: Messages are returned oldest first. Includes up to 50 most recent messages.

Get Messages

Get messages in a conversation.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/conversations/conversation-uuid/messages?limit=50' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": [ { "object": "message", "id": "message-uuid", "text": "Hi John, thanks for your interest...", "timestamp": "2025-11-27T10:00:00Z", "is_from_self": true, "is_read": true, "author": { "id": "profile-uuid", "display_name": "My Name", "avatar_url": "https://...", "username": "my-linkedin-handle" }, "conversation_id": "conversation-uuid" }, { "object": "message", "id": "message-uuid-2", "text": "That sounds great! Let's schedule a call.", "timestamp": "2025-11-27T10:30:00Z", "is_from_self": false, "is_read": true, "author": { "id": "profile-uuid-2", "display_name": "John Smith", "avatar_url": "https://...", "username": "johnsmith" }, "conversation_id": "conversation-uuid" } ], "pagination": { "total": 5, "limit": 50, "offset": 0, "hasMore": false }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Query Parameters:

Parameter	Type	Required	Description
`limit`	number	No	Results per page (default: 50, max: 100)
`offset`	number	No	Pagination offset (default: 0)

Note: Messages are returned oldest first (reversed from database order).

V1 API

bash

curl -X GET 'https://api.supersend.io/v1/conversation/conversation-uuid/messages?limit=50&order=asc' \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Conversation

Update conversation status (archive, mark read, etc.).

V2 API (Recommended)

bash

curl -X PATCH 'https://api.supersend.io/v2/conversations/conversation-uuid' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "is_archived": true, "is_unread": false, "mark_all_read": true }'

# Response (200 OK) { "success": true, "data": { "object": "conversation", "id": "conversation-uuid", "is_unread": false, "is_archived": true, "updated_at": "2025-11-27T10:35:00Z" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Update Parameters:

Parameter	Type	Required	Description
`is_archived`	boolean	No	Archive/unarchive conversation
`is_unread`	boolean	No	Mark conversation as read/unread
`mark_all_read`	boolean	No	Mark all messages in conversation as read

Note: At least one parameter is required.

Send Message

Send a message in a conversation. The endpoint automatically detects the conversation's platform type (email, LinkedIn, or Twitter) and routes the message appropriately.

V2 API (Recommended)

Sending an Email Reply

bash

curl -X POST 'https://api.supersend.io/v2/conversations/conversation-uuid/messages' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Thank you for your interest! I would love to schedule a call.", "sender_id": "sender-uuid", "subject": "Re: Partnership Opportunity", "is_html": false }'

# Response (201 Created) { "success": true, "data": { "object": "message", "id": "message-uuid", "text": "Thank you for your interest! I would love to schedule a call.", "subject": "Re: Partnership Opportunity", "timestamp": "2026-01-28T11:00:00Z", "is_from_self": true, "is_read": true, "status": "pending", "job_id": "job-uuid", "conversation_id": "conversation-uuid", "platform_type": "email", "sender": { "id": "sender-uuid", "email": "sales@company.com" } }, "request_id": "req_a1b2c3d4e5f6789012345678" }

Sending a LinkedIn Message

bash

curl -X POST 'https://api.supersend.io/v2/conversations/conversation-uuid/messages' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Thanks for connecting! Would love to chat about your work." }'

# Response (201 Created) { "success": true, "data": { "object": "message", "id": "message-uuid", "text": "Thanks for connecting! Would love to chat about your work.", "timestamp": "2026-01-28T11:00:00Z", "is_from_self": true, "is_read": true, "status": "pending", "job_id": "job-uuid", "conversation_id": "conversation-uuid", "platform_type": "linkedin" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Send Message Parameters:

Parameter	Type	Required	Description
`message`	string	Yes	Message text (1-8000 characters)
`sender_id`	string	Email only	Sender/mailbox ID (required for email conversations)
`subject`	string	No	Email subject (email only, defaults to "Re: {title}")
`is_html`	boolean	No	HTML formatted message (email only, default: false)
`to`	string	No	Override recipient email (email only, auto-selected if not provided)
`cc`	array	No	CC recipients (email only)
`bcc`	array	No	BCC recipients (email only)
`attachments`	array	No	Email attachments (email only)

Platform Support:

Email: Requires sender_id. Supports full email features (subject, cc, bcc, attachments, HTML)

LinkedIn: Only requires message. Queued for delivery via LinkedIn executor

Twitter: Not yet supported via API (returns error with instructions to use SuperSend inbox)

Note:

Message is queued for async delivery

Response includes status: "pending" and job_id for tracking

Message is created optimistically and will be updated when delivery completes

The platform_type field in the response indicates which channel was used

Inbox Counts (V1 Only)

Get counts for different conversation categories.

bash

curl -X GET 'https://api.supersend.io/v1/conversation/counts?TeamId=xxx&channel=email' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response { "success": true, "data": { "inbox": 25, "campaignReplies": 15, "nonCampaignReplies": 10, "sent": 5, "all": 30, "archived": 8 } }

Platform Types

Platform	V2 Value	V1 Value
LinkedIn	`linkedin`	1
Twitter	`twitter`	2
Email	`email`	3

V1 vs V2 Endpoint Mapping

Action	V1 Endpoint	V2 Endpoint
List	`GET /v1/conversation/latest-by-profile`	`GET /v2/conversations`
Get	`GET /v1/conversation/:id`	`GET /v2/conversations/:id`
Update	Not available	`PATCH /v2/conversations/:id`
Get Messages	`GET /v1/conversation/:id/messages`	`GET /v2/conversations/:id/messages`
Send Message	Various V1 endpoints	`POST /v2/conversations/:id/messages`
Get Counts	`GET /v1/conversation/counts`	Not available in V2