> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List messages

> This endpoint lists messages.

### URL Params

<ParamField query="campaign" type="string" required>
  The ID of the campaign to list messages from.
</ParamField>

<ParamField query="limit" type="number">
  The number of messages to return (default 10).
</ParamField>

<ParamField query="skip" type="number">
  The number of messages to skip (i.e. offset).
</ParamField>

<ParamField query="direction" type="string">
  Return either `INBOUND` or `OUTBOUND` messages.
</ParamField>

<ParamField query="number" type="string">
  Return messages to/from a specific number.
</ParamField>

### Response

<ResponseField name="messages" type="[message]">
  An array of message objects returned.

  <Expandable title="message fields">
    <ResponseField name="id" type="string" required>
      The ID of the retrieved message.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Message type. Either `SMS` or `MMS`.
    </ResponseField>

    <ResponseField name="createdAt" type="timestamp" required>
      The time that the message was created.
    </ResponseField>

    <ResponseField name="sentAt" type="timestamp or null">
      The time that the message was sent.
    </ResponseField>

    <ResponseField name="updatedAt" type="timestamp or null">
      The time of the most recent status update.
    </ResponseField>

    <ResponseField name="scheduledAt" type="timestamp or null">
      The time the message is scheduled for (optional).
    </ResponseField>

    <ResponseField name="direction" type="string" required>
      Message direction. Either `INBOUND` or `OUTBOUND`.
    </ResponseField>

    <ResponseField name="from" type="string" required>
      The number that the message was sent from.
    </ResponseField>

    <ResponseField name="to" type="string" required>
      The number that the message was sent to.
    </ResponseField>

    <ResponseField name="body" type="string" required>
      The body of the message.
    </ResponseField>

    <ResponseField name="mediaUrls" type="[string]">
      Array of media URLs attached to the message.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Object with user-defined key-value pairs.
    </ResponseField>

    <ResponseField name="numSegments" type="number" required>
      Number of message segments sent [(see guide)](/knowledge-base/segments).
    </ResponseField>

    <ResponseField name="errorCode" type="number or null">
      The error code (if the message fails).
    </ResponseField>

    <ResponseField name="errorMessage" type="string or null">
      The error message (if the message fails).
    </ResponseField>

    <ResponseField name="campaignId" type="string" required>
      ID of the campaign that the message was sent from.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      The status of the message.

      <Expandable title="message statuses">
        <ResponseField name="CREATED" type="string">
          The message has been created.
        </ResponseField>

        <ResponseField name="QUEUED" type="string">
          The message is queued for sending.
        </ResponseField>

        <ResponseField name="SCHEDULED" type="string">
          The message is scheduled for sending.
        </ResponseField>

        <ResponseField name="SENT" type="string">
          The message has been sent.
        </ResponseField>

        <ResponseField name="DELIVERED" type="string">
          The message has been delivered.
        </ResponseField>

        <ResponseField name="READ" type="string">
          The message has been opened.
        </ResponseField>

        <ResponseField name="FAILED" type="string">
          The message send has failed.
        </ResponseField>

        <ResponseField name="EXPIRED" type="string">
          The send has failed after too many attempts.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the request fails.
</ResponseField>

#### Errors

If the request fails, it will return an HTTP error status code and an `error` field in the response body with details. Full list of status codes [here](/api-reference/introduction).

<ResponseExample>
  ```json Success theme={null}
  {
    "messages": [
      {
        "id": "f7d258bd-f697-4840-b8a6-165707e12345",
        "type": "SMS",
        "createdAt": "2023-09-19T04:55:50.723Z",
        "sentAt": "2023-09-19T04:55:50.723Z",
        "updatedAt": "2023-09-19T04:55:55.884Z",
        "direction": "INBOUND",
        "from": "+14159436397",
        "to": "+12061234567",
        "body": "Incoming message",
        "numSegments": 1,
        "campaignId": "U7fQ3123",
        "status": "DELIVERED"
      },
      {
        "id": "f7d258bd-f697-4840-b8a6-165707e12123",
        "type": "MMS",
        "createdAt": "2023-09-19T04:55:50.723Z",
        "sentAt": "2023-09-19T04:55:50.723Z",
        "updatedAt": "2023-09-19T04:55:55.884Z",
        "direction": "INBOUND",
        "from": "+14159436397",
        "to": "+12061234567",
        "body": "Another incoming message",
        "mediaUrls": ["https://example.com/image.jpg"],
        "numSegments": 1,
        "campaignId": "U7fQ3123",
        "metadata": {
          "customId": "123456789"
        },
        "status": "DELIVERED"
      },
      And so on...
    ]
  }
  ```

  ```json Error theme={null}
  {
    "messages": null,
    "error": "Internal server error"
  }
  ```
</ResponseExample>