> ## 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.

> [!TIP]
>
> For real-time inbound notifications, use the
> `message.received`
> [webhook](https://docs.metriport.com/medical-api/handling-data/webhooks-with-nq.md#message-received)
> rather than polling this endpoint.

This is a paginated endpoint. For more information see [pagination](https://docs.metriport.com/medical-api/handling-data/pagination.md).

## Query Params

**direction** `string`

Filter messages by direction. One of `outbound` or
`inbound`. If not provided, both directions are returned.

**patientId** `string`

Filter messages to those related to a specific Patient.

**destination** `string`

Filter messages by exact destination.

**status** `string`

Filter messages by status. One of `processing`, `completed`, or `failed`.

## Response

**meta** `object` *required*

Pagination metadata. See
[pagination](https://docs.metriport.com/medical-api/handling-data/pagination.md).

An array of Message objects representing inbound and outbound messages.

**messages** `Message[]` *required*

**Message properties**

<Snippet file="message-response.mdx" />

```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"
    }
  ]
}
```

```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",
});
```

## Rate Limits

See [limits and throttling](https://docs.metriport.com/medical-api/more-info/limits.md#rate-limits)


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