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

## Response

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

An array of [Communication](/medical-api/fhir/resources/communication) resources representing inbound and outbound messages.
These resources also appear in the patient's [Consolidated Data](/medical-api/api-reference/fhir/consolidated-data-query-post) bundle.

<ResponseField name="messages" type="Communication[]" required>
  See FHIR [Communication](/medical-api/fhir/resources/communication). Key properties populated for messages:

  <Expandable title="Communication properties">
    <ResponseField name="resourceType" type="string" required>
      Always `Communication`.
    </ResponseField>

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

    <ResponseField name="status" type="code" required>
      The delivery status. See [Communication.status](/medical-api/fhir/resources/communication#properties).
      For outbound messages, one of `in-progress`, `completed`,
      `not-done` (error on the recipient's end).
      For inbound messages, `completed`.
    </ResponseField>

    <ResponseField name="statusReason" type="code">
      Reason for the status. Will only be provided if the status is `not-done`.
    </ResponseField>

    <ResponseField name="subject" type="Reference" required>
      Reference to the [Patient](/medical-api/fhir/resources/patient) the message relates to. May be absent for unmatched inbound messages.
    </ResponseField>

    <ResponseField name="topic" type="CodeableConcept">
      The subject line of the message.
    </ResponseField>

    <ResponseField name="sender" type="Reference">
      Your organization's name.
    </ResponseField>

    <ResponseField name="recipient" type="Reference[]">
      The intended recipient(s). Present on outbound messages. See [Communication.recipient](/medical-api/fhir/resources/communication#properties).
    </ResponseField>

    <ResponseField name="sent" type="dateTime">
      ISO 8601 timestamp of when the message was sent. Present on outbound messages.
    </ResponseField>

    <ResponseField name="received" type="dateTime">
      ISO 8601 timestamp of when the message was received. Present on inbound messages.
    </ResponseField>

    <ResponseField name="payload" type="CommunicationPayload[]">
      The message body and attached documents. See [Communication.payload](/medical-api/fhir/resources/communication#properties).
    </ResponseField>

    <ResponseField name="extension" type="Extension[]">
      Metriport extensions, including message direction (`outbound` or `inbound`).
    </ResponseField>
  </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": [
    {
      "resourceType": "Communication",
      "id": "00000000-0000-0000-0000-000000000000",
      "status": "completed",
      "subject": {
        "reference": "Patient/00000000-0000-0000-0000-000000000000",
        "type": "Patient"
      },
      "topic": {
        "text": "Referral - cardiology"
      },
      "sender": {
        "display": "Your Organization Name"
      },
      "recipient": [
        {
          "type": "Organization",
          "display": "1.2.840.114350.1.13.300.3.7.3.688884.100.1"
        },
        {
          "type": "Practitioner",
          "display": "1234567893"
        }
      ],
      "sent": "2026-06-16T18:40:00.000Z",
      "payload": [
        {
          "contentReference": {
            "reference": "DocumentReference/00000000-0000-0000-0000-000000000000"
          }
        }
      ],
      "extension": [
        {
          "url": "https://public.metriport.com/fhir/StructureDefinition/data-source.json",
          "valueCoding": {
            "system": "https://public.metriport.com/fhir/StructureDefinition/data-source.json",
            "code": "METRIPORT"
          }
        }
      ]
    },
    {
      "resourceType": "Communication",
      "id": "11111111-1111-1111-1111-111111111111",
      "status": "completed",
      "subject": {
        "reference": "Patient/00000000-0000-0000-0000-000000000000",
        "type": "Patient"
      },
      "topic": {
        "text": "Follow-up notes"
      },
      "sender": {
        "display": "referrals@cardio.direct.partner.com"
      },
      "recipient": [
        {
          "type": "Organization",
          "display": "Your Organization Name"
        },
        {
          "type": "Practitioner",
          "display": "1234567893"
        }
      ],
      "received": "2026-06-16T19:10:00.000Z",
      "payload": [
        {
          "contentReference": {
            "reference": "DocumentReference/11111111-1111-1111-1111-111111111111"
          }
        }
      ],
      "extension": [
        {
          "url": "https://public.metriport.com/fhir/StructureDefinition/data-source.json",
          "valueCoding": {
            "system": "https://public.metriport.com/fhir/StructureDefinition/data-source.json",
            "code": "MESSAGE_DELIVERY"
          }
        },
        {
          "url": "https://public.metriport.com/fhir/StructureDefinition/data-source.json",
          "valueCoding": {
            "system": "https://public.metriport.com/fhir/StructureDefinition/data-source.json",
            "code": "TEFCA"
          }
        }
      ]
    }
  ]
}
```

<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)