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

# List Messages

> List all inbound and outbound messages.

<Snippet file="in-construction.mdx" />

Returns all secure messages for your organization - both messages you have sent and messages received from other practitioners.

<Warning>
  Note that some inbound messages might not be tied to any
  specific patient.
</Warning>

<Tip>
  For real-time inbound notifications, use the
  `message.received`
  [webhook](/medical-api/handling-data/webhooks-with-nq#message-received)
  rather than polling this endpoint.
</Tip>

This is a paginated endpoint. For more information see [pagination](/medical-api/handling-data/pagination).

## Query Params

<ParamField query="direction" type="string" optional>
  Filter messages by direction. One of `outbound` or
  `inbound`. If not provided, both directions are returned.
</ParamField>

<ParamField query="patientId" type="string" optional>
  Filter messages to those related to a specific Patient.
</ParamField>

<ParamField query="destination" type="string" optional>
  Filter messages by exact destination.
</ParamField>

<ParamField query="status" type="string" optional>
  Filter messages by status. One of `processing`, `completed`, or `failed`.
</ParamField>

## Response

<ResponseField name="meta" type="object" required>
  Pagination metadata. See
  [pagination](/medical-api/handling-data/pagination).
</ResponseField>

An array of Message objects representing inbound and outbound messages.

<ResponseField name="messages" type="Message[]" required>
  <Expandable title="Message properties">
    <Snippet file="message-response.mdx" />
  </Expandable>
</ResponseField>

```json theme={null}
{
  "meta": {
    "nextPage": "https://api.metriport.com/medical/v1/message?fromItem=33333333-3333-3333-3333-333333333333&count=50&direction=outbound",
    "itemsOnPage": 2,
    "itemsInTotal": 14
  },
  "messages": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "patientId": "11111111-1111-1111-1111-111111111111",
      "direction": "outbound",
      "status": "completed",
      "transportMethod": "xdr",
      "network": "EHEX",
      "destination": "2.16.840.1.113883.3.666.123.4.101",
      "subject": "Referral - cardiology",
      "body": "Please review the attached referral for cardiology consultation.",
      "attachments": ["00000000-0000-0000-0000-000000000000"],
      "intendedRecipientNpi": ["1234567890"],
      "sentAt": "2026-06-16T18:40:00.000Z",
      "updatedAt": "2026-06-16T18:42:11.000Z"
    },
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "patientId": "11111111-1111-1111-1111-111111111111",
      "direction": "inbound",
      "status": "completed",
      "transportMethod": "direct",
      "destination": "your-org@direct.example.org",
      "subject": "Follow-up notes",
      "body": "Please see attached follow-up notes.",
      "attachments": ["22222222-2222-2222-2222-222222222222"],
      "sentAt": "2026-06-16T19:10:00.000Z",
      "updatedAt": "2026-06-16T19:10:00.000Z"
    }
  ]
}
```

<ResponseExample>
  ```javascript Metriport SDK theme={null}
  import { MetriportMedicalApi } from "@metriport/api-sdk";

  const metriport = new MetriportMedicalApi("YOUR_API_KEY");

  const { meta, messages } = await metriport.listMessages({
    direction: "outbound",
    patientId: "00000000-0000-0000-0000-000000000000",
  });
  ```
</ResponseExample>

## Rate Limits

See [limits and throttling](/medical-api/more-info/limits#rate-limits)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.