List SMS Messages (v1)

Method & Path

GET /api/v1/workspace/:workspaceId/sms/messages

Description

Get a paginated list of SMS messages with optional filtering.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with workspace permissions.

Headers

Authorization: Bearer <workspace_token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Number of results per page (default: 50)
offset	number	No	Number of results to skip (default: 0)
type	string	No	Filter by message type (otp, notification, other)
status	string	No	Filter by status (pending, sent, failed)

Response 200 OK

{
  "messages": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439012",
      "type": "otp",
      "status": "sent",
      "recipient": "+1234567890",
      "message": "Your OTP code is 123456",
      "cost": 0.05,
      "sentAt": "2025-01-15T10:30:00.000Z",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Response Fields

messages

Array of SMS message objects:

• id (string): Message identifier
• workspaceId (string): Workspace identifier
• type (string): Message type (otp, notification, other)
• status (string): Delivery status (pending, sent, failed)
• recipient (string): Recipient phone number
• message (string): Message content
• cost (number): Cost of this message
• sentAt (string | null): Timestamp when message was sent (ISO 8601 format)
• createdAt (string): Creation timestamp (ISO 8601 format)

pagination

• total (number): Total number of messages
• limit (number): Number of results per page
• offset (number): Number of results skipped
• hasMore (boolean): Whether there are more results

Common Errors

400 Bad Request: Invalid query parameters

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have permission to view SMS data

404 Not Found: Workspace not found

500 Internal Server Error: Server error occurred while processing the request