List a message's recipients

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

v2Operation ID v2_public_messages_recipients_index

Lists everyone a message was sent to, with how delivery went for each: the address or number it went to at the time, the channel (email or sms), the status, and the provider's error when it failed. All of them, not paged.

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.

dataarray of objectsrequired
Fields of each item (13)
- callback_error_codestring | null
  The provider's error code, when delivery failed: for emails the bounce type, such as HardBounce; for texts Twilio's error code.
- callback_error_messagestring | null
  The provider's details.
- channelstring | null
  - One of: "email", "sms"
- delivery_statestring | null
  From the provider's report. Null for older messages.
  - One of: "pending", "sending", "sent", "delivered", "failed", "unknown"
- destinationstring | null
  Where it was sent: the email address or phone number at sending time.
- destination_namestring | null
- idstring
  The recipient (delivery) id.
- latest_error_reasonstring | null
  Why it failed, in words: the provider's description, or YoPrint's own reason, such as missing_delivery_destination, mailable_serialization_failed or postmark_retry_mailable_unavailable (see the retry operations).
- participantobject | null
  The participant it went to. Its delivery_* fields are null; read them from this recipient.
  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"
- recipient_emailstring | null
  The address, for an email recipient.
- recipient_phonestring | null
  The number, for a text recipient.
- statusstring
  pending also while a retry is in progress.
  - One of: "pending", "dispatched", "dispatch_failed", "delivered", "delivery_failed"
- versioninteger
  The record's tracking format: 1, then 2 once the email or text provider has reported on it. Not the message's version.
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.
Fix
Use an id from the message list.

GETGet one recipient of a message/v2/api/store/{team_slug}/messages/{hash_id}/recipients/{id}
PUTRetry delivery to one recipient/v2/api/store/{team_slug}/messages/{hash_id}/recipients/{id}/retry

Example request

curl

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

Example response 200

{
  "data": [
    {
      "callback_error_code": "HardBounce",
      "callback_error_message": "The mailbox does not exist.",
      "channel": "email",
      "delivery_state": "failed",
      "destination": "jordan@example.com",
      "destination_name": "Jordan Lee",
      "id": "XWwTVKIZSuUOcX",
      "latest_error_reason": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
      "participant": {
        "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": null,
        "delivery_created_at": null,
        "delivery_destination": null,
        "delivery_destination_name": null,
        "delivery_id": null,
        "delivery_latest_error_reason": null,
        "delivery_message_id": null,
        "delivery_participant_id": null,
        "delivery_state": null,
        "delivery_status": null,
        "delivery_updated_at": null,
        "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"
      },
      "recipient_email": "jordan@example.com",
      "recipient_phone": null,
      "status": "delivery_failed",
      "version": 2
    }
  ],
  "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