Log InHome Page

APIs

Conversation API

Conversations represent email, LinkedIn, or Twitter message threads. You can retrieve conversations, send messages, forward conversations, and manage read/unread status.

Get Inbox Counts

Get counts for different conversation categories (inbox, campaign replies, non-campaign replies, sent, all, archived).

Query Parameters:

Required:

  • None (authentication via Bearer token)

Optional:

  • TeamId - string - Filter by team ID
  • channel - string - Channel type: email (default), linkedin, twitter
  • CampaignId - string - Filter by campaign ID
  • CampaignIds - string or array - Filter by multiple campaign IDs (comma-separated)
  • SenderId - string - Filter by sender ID
  • SenderIds - string or array - Filter by multiple sender IDs (comma-separated)
  • LabelId - string - Filter by label ID
  • LabelIds - string or array - Filter by multiple label IDs (comma-separated)
  • LabelCountIds - string or array - Get per-label counts for specific label IDs
  • ExcludeLabelIds - string or array - Exclude conversations with these label IDs
  • from - string - Filter by start date
  • to - string - Filter by end date
  • search - string - Search in conversation content
  • Mood - string - Filter by mood
  • status - string - Filter by status: read, unread, archived, unarchived
  • only - string - Comma-separated list of counts to fetch: inbox, campaignReplies, nonCampaignReplies, sent, all, archived (default: all)
  • useMaster - boolean - Use master database (default: true)
curl -X GET 'https://api.supersend.io/v1/conversation/counts?TeamId=xxx&channel=email&status=unread' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "success": true,
  "data": {
    "inbox": 25,
    "campaignReplies": 15,
    "nonCampaignReplies": 10,
    "sent": 5,
    "all": 30,
    "archived": 8,
    "labelCounts": {
      "label-uuid-1": 5,
      "label-uuid-2": 3
    }
  }
}

Get Latest Conversations by Profile

Get the latest conversation per person/profile with support for filtering and pagination. Returns one conversation per PlatformPersonProfile based on most recent activity.

Query Parameters:

Required:

  • None (authentication via Bearer token)

Optional:

  • TeamId - string - Filter by team ID
  • status - string - Filter by status
  • search - string - Search in conversation content
  • sortBy - string - Sort field (default: last_activity_at)
  • sortDirection - string - Sort direction: ASC or DESC (default: DESC)
  • limit - number - Number of records to return (default: 20)
  • offset - number - Number of records to skip (default: 0)
  • SenderId - string - Filter by sender ID
  • SenderIds - string or array - Filter by multiple sender IDs
  • from - string - Filter by start date
  • to - string - Filter by end date
  • channel - string - Channel type: email (default), linkedin, twitter
  • repliesOnly - boolean - Filter to only replies
  • filterCategory - string - Filter category: inbox, campaign_replies, non-campaign, sent
  • LabelId - string - Filter by label ID
  • LabelIds - string or array - Filter by multiple label IDs
  • ExcludeLabelIds - string or array - Exclude conversations with these label IDs
  • last_message_direction - string - Filter by last message direction
  • CampaignId - string - Filter by campaign ID
  • CampaignIds - string or array - Filter by multiple campaign IDs
  • archived - string - Filter archived: true or false (default: false)
  • Mood - string - Filter by mood
curl -X GET 'https://api.supersend.io/v1/conversation/latest-by-profile?TeamId=xxx&limit=20&offset=0&channel=email' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "conversation-uuid",
        "title": "Re: Partnership Opportunity",
        "last_activity_at": "2025-11-27T10:30:00Z",
        "is_unread": true,
        "platform_type": 3,
        "inbox_mood": null,
        "contact_id": "contact-uuid",
        "labels": [
          {
            "id": "label-uuid",
            "name": "Interested",
            "color": "#4CAF50"
          }
        ]
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0
    }
  }
}

Get Conversation Messages

Get messages for a specific conversation.

Path Parameters:

  • conversationId - string (required) - Conversation UUID

Query Parameters:

Optional:

  • limit - number - Number of messages to return (default: 200, max: 500)
  • offset - number - Number of messages to skip (default: 0)
  • order - string - Sort order: asc or desc (default: asc)
curl -X GET 'https://api.supersend.io/v1/conversation/<conversationId>/messages?limit=50&offset=0&order=asc' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "success": true,
  "data": {
    "conversation": {
      "id": "conversation-uuid",
      "title": "Re: Partnership Opportunity",
      "last_activity_at": "2025-11-27T10:30:00Z",
      "is_unread": true,
      "platform_type": 3,
      "inbox_mood": null
    },
    "messages": [
      {
        "id": "message-uuid",
        "platform_message_id": "msg-123",
        "message_text": "Hi John, thanks for reaching out...",
        "html_content": "<p>Hi John, thanks for reaching out...</p>",
        "is_from_self": false,
        "timestamp": "2025-11-27T10:30:00Z",
        "is_read": false,
        "subject": "Re: Partnership Opportunity",
        "createdAt": "2025-11-27T10:30:00Z",
        "MessageAuthor": {
          "id": "profile-uuid",
          "username": "john@example.com",
          "display_name": "John Doe",
          "avatar_url": "https://example.com/avatar.jpg",
          "platform_type": 3
        },
        "Attachments": [
          {
            "id": "attachment-uuid",
            "filename": "document.pdf",
            "file_path": "path/to/document.pdf"
          }
        ]
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "count": 5
    }
  }
}

Get Reply Recipients

Get valid reply recipients for a conversation (excluding BCC and self).

Path Parameters:

  • conversationId - string (required) - Conversation UUID
curl -X GET 'https://api.supersend.io/v1/conversation/<conversationId>/reply-recipients' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "success": true,
  "recipients": [
    {
      "email": "john@example.com",
      "displayName": "John Doe",
      "type": "TO",
      "label": "John Doe (TO)"
    },
    {
      "email": "jane@example.com",
      "displayName": "Jane Smith",
      "type": "CC",
      "label": "Jane Smith (CC)"
    }
  ]
}

Sync Conversations

Enqueue jobs to fetch latest conversations for the organization. Optionally accepts sender IDs to limit to specific senders.

Request Body:

Optional:

  • senderIds - array - Array of sender UUIDs to sync (default: all active senders)
  • TeamId - string - Team ID to filter senders
  • trigger - string - Trigger identifier (default: api_manual, max: 64 characters)
curl -X POST 'https://api.supersend.io/v1/conversation/sync' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "senderIds": ["sender-uuid-1", "sender-uuid-2"],
  "TeamId": "team-uuid",
  "trigger": "api_manual"
}'

# Response
{
  "success": true,
  "message": "Conversation sync jobs enqueued",
  "data": {
    "queued": 5,
    "skippedAlreadyQueued": 2,
    "totalEligible": 7,
    "TeamId": "team-uuid"
  }
}

Get Profile Conversations

Get profile details, all conversations for that profile, and matching contact IDs.

Path Parameters:

  • profileId - string (required) - PlatformPersonProfile UUID

Query Parameters:

Required:

  • TeamId - string - Team identifier

Optional:

  • archived - boolean - Include archived conversations (default: false)
curl -X GET 'https://api.supersend.io/v1/conversation/latest-by-profile/<profileId>?TeamId=xxx&archived=false' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "success": true,
  "data": {
    "profile": {
      "id": "profile-uuid",
      "username": "john@example.com",
      "display_name": "John Doe",
      "avatar_url": "https://example.com/avatar.jpg",
      "platform_type": 3
    },
    "conversations": [
      {
        "id": "conversation-uuid",
        "title": "Re: Partnership Opportunity",
        "last_activity_at": "2025-11-27T10:30:00Z",
        "is_unread": true,
        "avatar_url": null,
        "platform_type": 3,
        "platform_conversation_id": "thread-123",
        "inbox_mood": null,
        "unread_messages_count": 2,
        "contact_id": "contact-uuid",
        "labels": [
          {
            "id": "label-uuid",
            "name": "Interested",
            "color": "#4CAF50"
          }
        ]
      }
    ],
    "linkedin_profiles": []
  }
}

Send Email Message

Send an email message within a conversation. Enqueues a send job to the email queue.

Path Parameters:

  • conversationId - string (required) - Conversation UUID

Request Body:

Required:

  • message - string - Message content (min length: 1)
  • senderId - string - Sender UUID

Optional:

  • subject - string - Email subject (default: "Re: {conversation.title}")
  • isHtml - boolean - Whether message is HTML (default: false)
  • to - string - Recipient email address (optional, uses conversation participants if not provided)
  • cc - array - CC email addresses
  • bcc - array - BCC email addresses
  • attachments - array - Attachment objects
curl -X POST 'https://api.supersend.io/v1/conversation/<conversationId>/send-email' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "message": "Thanks for your interest! Let me know if you have any questions.",
  "senderId": "sender-uuid",
  "subject": "Re: Partnership Opportunity",
  "isHtml": false,
  "to": "john@example.com",
  "cc": ["team@example.com"],
  "bcc": [],
  "attachments": []
}'

# Response
{
  "success": true,
  "message": "Email queued for sending",
  "tempMessageId": "temp-message-uuid",
  "job_id": "job-uuid"
}

Forward Conversation

Forward a conversation thread as an email. Formats all messages in the thread and sends them as a forwarded email.

Path Parameters:

  • conversationId - string (required) - Conversation UUID

Request Body:

Required:

  • to - string - Recipient email address
  • senderId - string - Sender UUID

Optional:

  • message - string - Optional message to include before forwarded content
  • cc - array - CC email addresses
  • bcc - array - BCC email addresses
curl -X POST 'https://api.supersend.io/v1/conversation/<conversationId>/forward' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "to": "forward@example.com",
  "senderId": "sender-uuid",
  "message": "Please review this conversation",
  "cc": ["team@example.com"],
  "bcc": []
}'

# Response
{
  "success": true,
  "message": "Conversation forwarded successfully",
  "data": {
    "messageId": "message-id-from-provider"
  }
}

Mark Conversation as Read

Mark a conversation and all its messages as read.

Path Parameters:

  • conversationId - string (required) - Conversation UUID
curl -X PUT 'https://api.supersend.io/v1/conversation/<conversationId>/read' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "success": true,
  "message": "Conversation marked as read"
}

Mark Conversation as Unread

Mark a conversation as unread.

Path Parameters:

  • conversationId - string (required) - Conversation UUID
curl -X PUT 'https://api.supersend.io/v1/conversation/<conversationId>/unread' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "success": true,
  "message": "Conversation marked as unread"
}
Previous
Sequence
Next
Managed Domains