> ## Documentation Index > Fetch the complete documentation index at: https://docs.senderkit.com/llms.txt > Use this file to discover all available pages before exploring further. # List messages > Returns messages for the authenticated workspace and environment, newest first, with cursor pagination. Setting `tail=1` switches the endpoint to a Server-Sent Events stream (`text/event-stream`) that backfills the most recent 50 messages and then pushes new ones live. Streams are closed by the server after 30 minutes; EventSource clients reconnect automatically and receive a fresh backfill. The schemas below describe the non-streaming JSON response. ## OpenAPI ````yaml https://www.senderkit.com/openapi.yaml get /v1/messages openapi: 3.1.0 info: title: SenderKit Public API version: 1.0.0 description: > Public REST API for SenderKit — send transactional messages (email, SMS, push, web push), list message history, and read/render templates. ## Authentication All endpoints require a Bearer API key: Authorization: Bearer sk_live_xxx The `sk_live_` / `sk_test_` prefix selects the environment (live vs. test). The prefix is only a hint for humans; the secret is the full token. Keys are created in the dashboard and shown once at creation. ## Sends are asynchronous `POST /v1/send` enqueues the message and returns `202` with `status: "queued"`. Delivery happens out of band; poll `GET /v1/messages` to observe progress. ## Rate limits All endpoints are rate limited per API key. Sends and reads count against separate budgets, so listing messages never competes with sending them. A `429` response includes a `Retry-After` header (seconds). servers: - url: https://api.senderkit.com description: Production - url: http://localhost:3000/api description: Local development security: - apiKey: [] tags: - name: Context description: Inspect the workspace and environment an API key operates in. - name: Send description: Dispatch messages. - name: Messages description: Read message history and cancel pending sends. - name: Templates description: Read and render stored templates. paths: /v1/messages: get: tags: - Messages summary: List messages description: | Returns messages for the authenticated workspace and environment, newest first, with cursor pagination. Setting `tail=1` switches the endpoint to a Server-Sent Events stream (`text/event-stream`) that backfills the most recent 50 messages and then pushes new ones live. Streams are closed by the server after 30 minutes; EventSource clients reconnect automatically and receive a fresh backfill. The schemas below describe the non-streaming JSON response. operationId: listMessages parameters: - name: limit in: query description: Page size (1–200). schema: type: integer minimum: 1 maximum: 200 default: 50 - name: cursor in: query description: Opaque pagination cursor from a previous response's `nextCursor`. schema: type: string - name: status in: query schema: $ref: '#/components/schemas/MessageStatus' - name: channel in: query schema: $ref: '#/components/schemas/Channel' - name: template in: query description: Filter by template slug. schema: type: string - name: metadata[key] in: query description: | Filter by metadata containment, Stripe-style. E.g. `?metadata[userId]=usr_123`. Multiple keys are AND-ed. Values that parse as numbers/booleans are coerced. schema: type: string - name: tail in: query description: Set to `1` to receive a Server-Sent Events stream instead of JSON. schema: type: string enum: - '1' responses: '200': description: A page of messages. content: application/json: schema: type: object required: - data - nextCursor properties: data: type: array items: $ref: '#/components/schemas/Message' nextCursor: type: - string - 'null' description: Cursor for the next page, or null if no more results. text/event-stream: schema: type: string description: | SSE stream (when `tail=1`). Events: `message` (a Message object), `ready` (backfill complete), `error` (`{ code, message }`; `poll_failed` errors are transient and the stream stays open). '400': description: Invalid `status` or `channel` filter value (`invalid_request`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' components: schemas: MessageStatus: type: string description: | Lifecycle status of a message. `scheduled` is the initial status for a send with a future `scheduledAt`; `queued` is the initial status for an immediate send. `canceled` is terminal and reached when a `scheduled` or `queued` message is canceled before dispatch. enum: - scheduled - queued - rendered - dispatched - sent - delivered - failed - opted_out - canceled Channel: type: string enum: - email - sms - push - web-push Message: type: object description: A message row. `vars`, `metadata`, and `timeline` are JSON. properties: id: type: string format: uuid workspaceId: type: string format: uuid publicId: type: string example: msg_0a1b2c3d4e5f6g7h templateSlug: type: - string - 'null' description: Null for raw sends. channel: $ref: '#/components/schemas/Channel' status: $ref: '#/components/schemas/MessageStatus' livemode: type: boolean recipient: type: string vars: type: object additionalProperties: true metadata: $ref: '#/components/schemas/Metadata' fromOverride: type: - string - 'null' fromNameOverride: type: - string - 'null' interpolate: type: boolean description: | Raw sends only — whether Mustache interpolation was run over the inline content. Always false for template sends. pinnedVersion: type: - integer - 'null' description: | Template sends only — the explicit template version pinned by the caller, or null when resolved by environment. provider: type: - string - 'null' providerConnectionId: type: - string - 'null' format: uuid providerMessageId: type: - string - 'null' latencyMs: type: - integer - 'null' openedAt: type: - string - 'null' format: date-time description: | First provider-reported open (email open tracking), or null. Set once; later opens don't update it. clickedAt: type: - string - 'null' format: date-time description: | First provider-reported link click, or null. Set once; later clicks don't update it. error: type: - string - 'null' timeline: type: array items: type: object properties: t: type: string format: date-time e: type: string additionalProperties: true createdAt: type: string format: date-time scheduledAt: type: - string - 'null' format: date-time description: | When the send was scheduled for, or null for an immediate send. idempotencyKey: type: - string - 'null' description: | The Idempotency-Key supplied on the send request, or null if none was provided. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code. example: invalid_request message: type: string issues: type: array description: Present on validation failures (Zod issues). items: type: object additionalProperties: true limit: type: integer description: Present on rate-limit errors. Metadata: type: object description: Caller-supplied tags/IDs. Values must be string, number, or boolean. additionalProperties: oneOf: - type: string - type: number - type: boolean responses: Unauthorized: description: Missing, malformed, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Rate limit exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: API key with an `sk_live_` or `sk_test_` prefix. ````