Messages

List Messages

List messages for a conversation, or tenant-wide by status/direction.

Conversation mode (conversation_id given): unchanged. Cursor or page pagination.

Tenant-wide mode (no conversation_id, but status and/or direction given): returns messages across all conversations of the tenant, newest first (created_at desc), page/page_size pagination only. Example: GET /messages?status=failed&direction=outbound&page_size=3 lists recent failed outbound messages. Limited to the last 30 days unless created_after is given. Each item is the normal message object (incl. error_message, conversation_id, contact_id, channel_id, platform); contact_id/channel_id fall back to the conversation's values when the message row has none.

Supports two pagination modes in conversation mode:

Supports two pagination modes:

  1. Page-based (standard): Use page and page_size parameters
  2. Cursor pagination (recommended for large datasets): Use cursor parameter for O(1) performance regardless of page number. Returns next_cursor in response.

For tables with billions of rows, always use cursor pagination.

Required Scopes: messages:read

get/api/v1/messages

Request

  • Base URL: https://api.sendseven.com
  • URL: https://api.sendseven.com/api/v1/messages
  • Auth: HTTP bearer

Query parameters

conversation_idstring nullable

Conversation UUID. Required unless a tenant-wide filter (status and/or direction) is given.

status'pending' | 'sent' | 'delivered' | 'read' | 'failed'

Message delivery status.

Note: Uses lowercase member names to match MySQL ENUM values exactly. Database has: enum('pending','sent','delivered','read','failed')

Tenant-wide mode only: filter by delivery status (e.g. failed).

direction'inbound' | 'outbound'

Message direction.

Note: Uses lowercase member names to match MySQL ENUM values exactly. Database has: enum('inbound','outbound')

Tenant-wide mode only: filter by direction (inbound / outbound).

created_afterstring date-time nullable

Tenant-wide mode only: only messages created at/after this ISO-8601 timestamp. Defaults to the last 30 days.

pageinteger

Page number (1-indexed)

page_sizeinteger

Items per page

cursorstring nullable

Cursor for efficient keyset pagination (overrides page)

Response

Successful Response

Example response

{
  "items": [
    {
      "attachments": [],
      "channel_id": "channel-123-456-789",
      "contact_id": "contact-123-456-789",
      "conversation_id": "conv-123-456-789",
      "created_at": "2025-01-15T10:30:00Z",
      "delivered_at": "2025-01-15T10:30:05Z",
      "direction": "inbound",
      "from": "+1234567890",
      "id": "msg-123-456-789",
      "message_type": "text",
      "platform": "whatsapp",
      "status": "delivered",
      "tenant_id": "tenant-123-456-789",
      "text": "Hello, I need help!"
    }
  ]
}

Changes

No recorded changes to this operation across all 3 revisions of this API.