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 messages for a specific conversation.

Get Latest Conversations by Profile

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

bash

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 Conversation Messages

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

Get Reply Recipients

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

Sync Conversations

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

bash

last_message_direction

Get Profile Conversations

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

bash

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
    }
  }
}

bash

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
    }
  }
}

Send Email Message

Mark a conversation and all its messages as read.

bash

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)"
    }
  ]
}

bash

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"
  }
}

Forward Conversation

Mark a conversation as unread.

bash

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": []
  }
}

Mark Conversation as Read

bash

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"
}

bash

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 Unread

bash

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"
}

Examples

bash

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"
}