Emails (Secure Links)

Send a secure email link for a document. Useful when you want recipients to access PHI via a time-limited link.

Send Secure Link

POST /emails — Sends a secure email link for a document.

Request Parameters (multipart form data)

Parameter	Required	Description
file	Yes	PDF or TIFF document to share
recipient_email	Yes	Email address of the recipient
recipient_name	No	Name of the recipient (displayed in email)
sender_name	No	Name of the sender (displayed in email)
reply_to_email	No	Reply-to email address
subject	No	Email subject line
note	No	Internal note for your reference
patient_name	No	Patient name for record keeping
patient_dob	No	Patient date of birth (YYYY-MM-DD)
expire_after	Yes	Days until link expires (1-180). Required; no default.
callback_url	No	URL to receive status callback

export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@./sample.pdf" \
  -F "recipient_email=recipient@example.com" \
  -F "recipient_name=Recipient" \
  -F "sender_name=Sender" \
  -F "subject=Secure Link" \
  -F "note=Referral" \
  -F "expire_after=30" \
  -F "callback_url=https://example.com/webhooks/email" \
  "$API_BASE/emails"

bash

export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@./sample.pdf" \
  -F "recipient_email=recipient@example.com" \
  -F "recipient_name=Recipient" \
  -F "sender_name=Sender" \
  -F "subject=Secure Link" \
  -F "note=Referral" \
  -F "expire_after=30" \
  -F "callback_url=https://example.com/webhooks/email" \
  "$API_BASE/emails"

export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@./sample.pdf" \
  -F "recipient_email=recipient@example.com" \
  -F "recipient_name=Recipient" \
  -F "sender_name=Sender" \
  -F "subject=Secure Link" \
  -F "note=Referral" \
  -F "expire_after=30" \
  -F "callback_url=https://example.com/webhooks/email" \
  "$API_BASE/emails"

Response

{
  "message": "Record has been sent, we will send a callback upon completion.",
  "emailId": "e5f6a7b8c9d0"
}

JSON

{
  "message": "Record has been sent, we will send a callback upon completion.",
  "emailId": "e5f6a7b8c9d0"
}

{
  "message": "Record has been sent, we will send a callback upon completion.",
  "emailId": "e5f6a7b8c9d0"
}

Get Email

GET /emails/:id — Retrieves details for a specific secure link email.

The :id parameter is the emailId returned when you created the email.

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/emails/REPLACE_EMAIL_ID" | jq

bash

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/emails/REPLACE_EMAIL_ID" | jq

curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/emails/REPLACE_EMAIL_ID" | jq

Response

{
  "senderName": "Example Provider",
  "recipientEmail": "recipient@example.com",
  "recipientName": "Dr. Example",
  "replyToEmail": null,
  "patientName": "John Doe",
  "patientDob": "1990-01-15",
  "recordStatus": null,
  "emailStatus": "success",
  "emailId": "e5f6a7b8c9d0",
  "secureLink": "https://records.medsender.com/...",
  "expiry": "2025-02-15T10:00:00.000Z",
  "sentAt": "2025-01-15T10:00:00.000Z",
  "note": "Referral documents",
  "subject": "Secure Medical Documents",
  "lastViewedAt": null,
  "isTest": false,
  "errorDetails": {
    "errorCode": null,
    "errorDetails": null
  }
}

JSON

{
  "senderName": "Example Provider",
  "recipientEmail": "recipient@example.com",
  "recipientName": "Dr. Example",
  "replyToEmail": null,
  "patientName": "John Doe",
  "patientDob": "1990-01-15",
  "recordStatus": null,
  "emailStatus": "success",
  "emailId": "e5f6a7b8c9d0",
  "secureLink": "https://records.medsender.com/...",
  "expiry": "2025-02-15T10:00:00.000Z",
  "sentAt": "2025-01-15T10:00:00.000Z",
  "note": "Referral documents",
  "subject": "Secure Medical Documents",
  "lastViewedAt": null,
  "isTest": false,
  "errorDetails": {
    "errorCode": null,
    "errorDetails": null
  }
}

{
  "senderName": "Example Provider",
  "recipientEmail": "recipient@example.com",
  "recipientName": "Dr. Example",
  "replyToEmail": null,
  "patientName": "John Doe",
  "patientDob": "1990-01-15",
  "recordStatus": null,
  "emailStatus": "success",
  "emailId": "e5f6a7b8c9d0",
  "secureLink": "https://records.medsender.com/...",
  "expiry": "2025-02-15T10:00:00.000Z",
  "sentAt": "2025-01-15T10:00:00.000Z",
  "note": "Referral documents",
  "subject": "Secure Medical Documents",
  "lastViewedAt": null,
  "isTest": false,
  "errorDetails": {
    "errorCode": null,
    "errorDetails": null
  }
}

Response Fields

Field	Description
emailId	Unique identifier for this email (use to retrieve status)
recipientEmail	Email address the link was sent to
recipientName	Recipient name if provided
senderName	Sender name if provided
replyToEmail	Reply-to email address if provided
subject	Email subject line
note	Internal note if provided
patientName	Patient name if provided
patientDob	Patient date of birth if provided
recordStatus	Status: "activated", "archived", "revoked", or null. Newly created emails can have null status.
emailStatus	Delivery status: "queued", "inprogress", "success", or "failure"
secureLink	The secure URL to view the document
expiry	When the secure link expires (ISO 8601)
sentAt	When the email was sent (ISO 8601)
lastViewedAt	When the link was last viewed, or null
isTest	Whether this was sent using test credentials
errorDetails	Error information if emailStatus is "failure"