Skip to main content
POST
/
medical
/
v1
/
message
Send Message
curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/message \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "destination": "<string>",
  "subject": "<string>",
  "body": "<string>",
  "attachments": [
    "<string>"
  ],
  "intendedRecipientNpi": [
    "<string>"
  ]
}
'
import { MetriportMedicalApi } from "@metriport/api-sdk";

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const status = await metriport.sendMessage({
  patientId: "11111111-1111-1111-1111-111111111111",
  destination: "intake@cardio.direct.partner.com",
  subject: "Referral - cardiology",
  body: "Please review the attached referral for cardiology consultation.",
  attachments: ["00000000-0000-0000-0000-000000000000"],
  intendedRecipientNpi: ["1234567890"],
});
This endpoint is currently under construction. Please reach out to support if you'd like to use it.
This endpoint sends a secure message containing a note and attached documents to another practitioner in the network regarding a specific patient’s clinical journey. Sending a message is an asynchronous process. The response returns a Communication resource immediately with the status being in-progress. The id can be used to Get Message Status. When the recipient acknowledges receipt, or if delivery fails, a webhook request will be sent to your configured URL:
  • message.status: can be one of completed or failed, depending on the outcome of the operation.
See the Message Delivery guide for the explanation of the full flow.

​
Query Params

​
patientId
string
required
The ID of the Patient the message relates to.

​
Body

​
destination
string
required
Where to deliver the message. Use Search Destinations to find a value, or pass one you already have. Can be an OID, or an email address.
​
subject
string
required
The subject of the message. Think of it as the subject field in an email.
​
body
string
Plain-text content of the message. At least one of body or attachments is required.
​
attachments
string[]
Document IDs that have already been uploaded to Metriport to attach to the message. At least one of body or attachments is required.
​
intendedRecipientNpi
string[]
Optional NPIs of the intended recipients. Useful when destination identifies an organization but the message is intended for specific practitioners.
Example Request Body: 
{
  "destination": "intake@cardio.direct.partner.com",
  "subject": "Referral - cardiology",
  "body": "Please review the attached referral for cardiology consultation.",
  "attachments": [
    "00000000-0000-0000-0000-000000000000",
    "11111111-1111-1111-1111-111111111111"
  ],
  "intendedRecipientNpi": ["1234567893"]
}

​
Response

​
communication
Communication
required
The resulting FHIR Communication resource.
{
  "communication": {
    "resourceType": "Communication",
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "in-progress",
    "subject": {
      "reference": "Patient/00000000-0000-0000-0000-000000000000"
    },
    "topic": {
      "text": "Referral - cardiology"
    },
    "sender": {
      "display": "Your Organization Name"
    },
    "recipient": [
      {
        "type": "Organization",
        "display": "intake@cardio.direct.partner.com"
      },
      {
        "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"
        }
      }
    ]
  }
}

import { MetriportMedicalApi } from "@metriport/api-sdk";

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const status = await metriport.sendMessage({
  patientId: "11111111-1111-1111-1111-111111111111",
  destination: "intake@cardio.direct.partner.com",
  subject: "Referral - cardiology",
  body: "Please review the attached referral for cardiology consultation.",
  attachments: ["00000000-0000-0000-0000-000000000000"],
  intendedRecipientNpi: ["1234567890"],
});

​
Rate Limits

See limits and throttling