Get a message

GET/v2/api/store/{team_slug}/messages/{hash_id}

v2Operation ID v2_public_messages_show

Returns one message in full: the message as written (message), the whole message as HTML (original_message), attachments, recipients with their delivery status, its team status, and retryable, which says whether a failed delivery can be sent again.

It has fields the list doesn't (display_type, message_participant_id, driver, message, original_message, retryable, message_status) and lacks some the list has (customer, vendor, is_order_rush, mode).

Permission

Any member can read purchase order messages. For sales order and quote messages you need permission to message all orders, or only the orders you created or are assigned to. The team owner sees everything.

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team
hash_idstringrequired
The message's id, from the message list. A hash id; unique keys and document numbers are refused with 404.
- Example u7HKhdhT6tkEUy

Request body

This operation takes no request body.

Response

200Successful response.

dataobjectrequired
Child fields (35)
- actor_namestring | null
  The writer's name, by actor_type: your team's name for system, the team member, the contact, the order's customer, the purchase order's vendor, the participant, or the name a guest gave. Null when YoPrint can't find the writer's record.
- actor_typestring
  Who wrote it: user, customer, vendor, contact (written in the customer or vendor portal), participant, guest (someone who is not a contact) or system.
- attachmentsarray of objects
  Files attached to it, in the same shape as an upload (id, name, file_name, mime_type, size, url).
- contactobject | null
  The contact who wrote it, when contact_id is set: first_name, last_name, email, phone and more.
- contact_idstring | null
- created_atstring (date-time)
- delivery_summaryobject | null
  Outbound messages: how delivery went across all recipients. Null for inbound messages.
  Child fields (12)
  - acceptedinteger
  - completeboolean
  - deliveredinteger
  - failedinteger
  - reasonstring | null
    Why the state is not final, or why nothing was sent, for example no_recipients or delivery_evidence_unavailable. Usually null.
  - retryableboolean
    True when the retry operation accepts this message. When false, it answers 422.
  - skippedinteger
  - statestring
    sent: the provider took it, delivery not confirmed yet. partial: recipients are in different states. not_sent: there were no recipients.
    One of: "pending", "sending", "sent", "delivered", "failed", "partial", "unknown", "not_sent"
  - submittinginteger
  - totalinteger
  - unknowninteger
  - waitinginteger
- display_typestring
  How the web app draws it, for example default_v2, or system_v2 for automatic messages.
- driverstring | null
  email, sms, or web for a message written in YoPrint.
- emailstring | null
  The sender's email address.
- has_messageboolean
- has_original_messageboolean
- idstring
- messagestring | null
  The message as it was written, without the email layout.
- message_participant_idstring | null
  The author, as a message participant.
- message_statusobject | null
  The status named by status_id: id, role (customer_message), type, label, customer_label, color, position, trashed.
- namestring | null
  The sender's name.
- order_idstring | null
  The sales order or quote it is on.
- order_object_typestring | null
  sales_order or quote. Null without an order.
- order_quoteboolean | null
- order_scoped_idstring | null
  The order's number, such as SO1001. An empty string "" (not null) without an order.
- original_messagestring | null
  The whole message as HTML: for a reply, the email as it arrived, with any quoted text; for a message you sent, the full message YoPrint rendered.
- participantobject | null
  The author, as a message participant, when message_participant_id is set. Its delivery_* fields are null.
  Child fields (24)
  - can_receive_mailboolean
  - can_receive_smsboolean
  - contactobject | null
    The contact, for type contact: first_name, last_name, email, phone and more.
  - contact_idstring | null
  - delivery_channelstring | null
    One of: "email", "sms"
  - delivery_created_atstring (date-time) | null
  - delivery_destinationstring | null
    The email address or phone number it went to.
  - delivery_destination_namestring | null
  - delivery_idstring | null
    The recipient id: the id the recipient operations take. Null on participant.
  - delivery_latest_error_reasonstring | null
  - delivery_message_idstring | null
  - delivery_participant_idstring | null
  - delivery_statestring | null
    From the provider's report. Null for older messages and on participant.
    One of: "pending", "sending", "sent", "delivered", "failed", "unknown"
  - delivery_statusstring | null
    One of: "pending", "dispatched", "dispatch_failed", "delivered", "delivery_failed"
  - delivery_updated_atstring (date-time) | null
  - emailstring | null
  - idstring
    The participant id. The recipient operations take delivery_id, not this.
  - namestring | null
  - order_idstring | null
  - phonestring | null
  - purchase_order_idstring | null
  - statusstring
    What they receive: message, notification, all or disabled.
  - trashedboolean
  - typestring
    user: a team member. contact: one of the customer's or vendor's contacts. guest: just a name and email.
    One of: "user", "contact", "guest"
- preview_messagestring | null
  A short plain-text preview.
- purchase_order_idstring | null
  The purchase order it is on.
- purchase_scoped_idstring | null
  The purchase order's number. Null when it is not on a purchase order.
- recipientsarray of objects
  Who it was sent to: each participant with its delivery (delivery_status, delivery_channel, delivery_destination). delivery_id is the id the recipient operations take.
  Fields of each item (24)
  - can_receive_mailboolean
  - can_receive_smsboolean
  - contactobject | null
    The contact, for type contact: first_name, last_name, email, phone and more.
  - contact_idstring | null
  - delivery_channelstring | null
    One of: "email", "sms"
  - delivery_created_atstring (date-time) | null
  - delivery_destinationstring | null
    The email address or phone number it went to.
  - delivery_destination_namestring | null
  - delivery_idstring | null
    The recipient id: the id the recipient operations take. Null on participant.
  - delivery_latest_error_reasonstring | null
  - delivery_message_idstring | null
  - delivery_participant_idstring | null
  - delivery_statestring | null
    From the provider's report. Null for older messages and on participant.
    One of: "pending", "sending", "sent", "delivered", "failed", "unknown"
  - delivery_statusstring | null
    One of: "pending", "dispatched", "dispatch_failed", "delivered", "delivery_failed"
  - delivery_updated_atstring (date-time) | null
  - emailstring | null
  - idstring
    The participant id. The recipient operations take delivery_id, not this.
  - namestring | null
  - order_idstring | null
  - phonestring | null
  - purchase_order_idstring | null
  - statusstring
    What they receive: message, notification, all or disabled.
  - trashedboolean
  - typestring
    user: a team member. contact: one of the customer's or vendor's contacts. guest: just a name and email.
    One of: "user", "contact", "guest"
- rendered_attachmentsarray of objects
  Everything attached when it was sent: the files (attachment_type media, upload shape) and generated documents such as the order PDF (attachment_type internal_attachment, with name and url).
- retryableboolean
  For outbound messages, the same as delivery_summary.retryable.
- statusstring | null
  Older delivery status word, such as pending, dispatched, partial_delivered, delivery_failed, delivered, or received for a reply. Prefer delivery_summary.
- status_idstring | null
  Your team's message status (for example "Needs reply"), set with the status operation. Null when none is set.
- systemboolean
  True for messages YoPrint sent automatically.
- typestring
  outbound: sent by your team. inbound: a reply received.
  - One of: "outbound", "inbound"
- userobject | null
  The team member who wrote it, when user_id is set.
  Child fields (5)
  - avatar_urlstring | null
  - emailstring
  - idstring
  - namestring
  - timezonestring | null
- user_idstring | null
statusintegerrequired
successbooleanrequired

Errors

401The API key is missing or wrong (unauthenticated).
403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.
When
The message is on a sales order or quote you can't message (user_is_not_authorized).
Fix
Ask a team admin for permission to message that order.
404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.
When
No message of this team has this id, or it is an internal notification.
Fix
Use an id from the message list.

GETList a message's recipients/v2/api/store/{team_slug}/messages/{hash_id}/recipients
PUTRetry a message's failed deliveries/v2/api/store/{team_slug}/messages/{hash_id}/retry
PUTSet a message's status/v2/api/store/{team_slug}/messages/{hash_id}/status

Example request

curl

curl 'https://secure.yoprint.com/v2/api/store/your-team/messages/u7HKhdhT6tkEUy' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1'

Example response 200

{
  "data": {
    "actor_name": "Alex Rivera",
    "actor_type": "user",
    "attachments": [],
    "contact": null,
    "contact_id": null,
    "created_at": "2026-11-03T09:30:00+00:00",
    "delivery_summary": {
      "accepted": 0,
      "complete": true,
      "delivered": 0,
      "failed": 1,
      "reason": null,
      "retryable": true,
      "skipped": 0,
      "state": "failed",
      "submitting": 0,
      "total": 1,
      "unknown": 0,
      "waiting": 0
    },
    "display_type": "default_v2",
    "driver": "email",
    "email": "alex@example.com",
    "has_message": true,
    "has_original_message": true,
    "id": "u7HKhdhT6tkEUy",
    "message": "<p>Your order is ready for pickup.</p>",
    "message_participant_id": null,
    "message_status": null,
    "name": "Alex Rivera",
    "order_id": "V4keXwwxMQyXw7",
    "order_object_type": "sales_order",
    "order_quote": false,
    "order_scoped_id": "SO1001",
    "original_message": "<html><body><p>Your order is ready for pickup.</p></body></html>",
    "participant": null,
    "preview_message": "Your order is ready for pickup.",
    "purchase_order_id": null,
    "purchase_scoped_id": null,
    "recipients": [
      {
        "can_receive_mail": true,
        "can_receive_sms": false,
        "contact": {
          "created_at": "2026-11-01T09:00:00+00:00",
          "customer_id": "63KcENAAsKuipY",
          "default_receive_sms": false,
          "email": "jordan@example.com",
          "external_type": null,
          "fax": null,
          "fax_country": null,
          "first_name": "Jordan",
          "id": "uTCR3hxPDePBUK",
          "is_external": false,
          "is_primary": true,
          "last_name": "Lee",
          "phone": "+1 201 555 0123",
          "phone_country": "US",
          "send_invoice": true,
          "trashed": false,
          "updated_at": "2026-11-01T09:00:00+00:00"
        },
        "contact_id": "uTCR3hxPDePBUK",
        "delivery_channel": "email",
        "delivery_created_at": "2026-11-03T09:30:00+00:00",
        "delivery_destination": "jordan@example.com",
        "delivery_destination_name": "Jordan Lee",
        "delivery_id": "XWwTVKIZSuUOcX",
        "delivery_latest_error_reason": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
        "delivery_message_id": "u7HKhdhT6tkEUy",
        "delivery_participant_id": "vKNPqQz8fsYDuT",
        "delivery_state": "failed",
        "delivery_status": "delivery_failed",
        "delivery_updated_at": "2026-11-03T09:31:00+00:00",
        "email": "jordan@example.com",
        "id": "vKNPqQz8fsYDuT",
        "name": "Jordan Lee",
        "order_id": "V4keXwwxMQyXw7",
        "phone": "+1 201 555 0123",
        "purchase_order_id": null,
        "status": "all",
        "trashed": false,
        "type": "contact"
      }
    ],
    "rendered_attachments": [],
    "retryable": true,
    "status": "delivery_failed",
    "status_id": null,
    "system": false,
    "type": "outbound",
    "user": {
      "avatar_url": "https://example.com/avatar.png",
      "email": "alex@example.com",
      "id": "VG7s3tFzyQbO2N",
      "name": "Alex Rivera",
      "timezone": "America/New_York"
    },
    "user_id": "VG7s3tFzyQbO2N"
  },
  "status": 200,
  "success": true
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com