Send a message to the customer

POST/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/message

v2Operation ID v2_public_order_message_store

Sends a message about a published sales order or quote to its participants, by email or text message, and saves it in the order's conversation.

Add the people who should receive it as participants first, then send their participant ids in participants.

Email limit: if your team goes over the daily email limit for its plan (60 a day on a free plan or trial, more on paid plans), YoPrint blocks email sending for your whole team until YoPrint support lifts the block. Space out bulk sends.

The answer is the saved message. {hash_id} is the order's id (for example V4keXwwxMQyXw7); the ord_ unique key is not accepted here. Use this rather than the v1 version, which also accepts drafts.

Permission

Needs permission to message this order's customer: the team owner, message_all_order, or message_self_order for orders the user created or is assigned to.

Business rules

Only published orders: drafts are refused ("No Permission - the resource is not yet created").
participants must be a non-empty list: an empty or missing list is refused with 422 "Participants are required".
Every participant id must belong to this order and not be removed: an id of another order's participant, a removed participant or an unknown id refuses the whole message with 422 participant_not_on_record ("A recipient is not on this record. Refresh the page and choose the recipients again."), and nothing is saved or sent. Use ids from this order's participant list.
Each participant must be able to receive the channel: email needs an email address (participant_cannot_receive_email), a text message needs can_receive_sms.
By email, every listed participant with an email address is sent the message, whatever their status or can_receive_mail. By text message, only those with can_receive_sms and status all or message. Leave out anyone who should not receive it.
At most 20 participants per message.
Deleted orders and Shopify orders refuse messages.
Messages count toward the team's daily email limit (60 a day on the free plan, and on a trial only once YoPrint support has turned email on for it; 280, 380 or 800 on paid plans depending on the subscription's age). Going over it blocks the team's email until YoPrint support lifts the block. A trial without email turned on, or a team without an active plan, gets 422 email_feature_not_enabled_in_trial.

Side effects

Sends the message to the participants by email (or text message) after it is saved, with the attachments. An email's link to the conversation opens it for the contact it was sent to.
The message is sent as the API key's user.
When the message shows in the customer portal (a published order that isn't from Shopify, with customer messages on), Customer Portal pages the order's customer has open refresh.

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team
hash_idstringrequired
The sales order's or quote's id (a hash id). The ord_ unique key and the order number do not work here.
- Example V4keXwwxMQyXw7

Request body

application/json, required.

messagestringrequired
The message. HTML for email; plain text for a text message.
participantsarray of objectsrequired
Who receives it: participant ids from this order's participants (not contact ids). Required, at least one. Every id must be a current participant of this order: one that isn't refuses the whole message with 422 participant_not_on_record, and nothing is sent. An id listed twice counts once.
- At most 20 items
Fields of each item (1)
- idstringrequired
  A participant id.
internal_attachmentsarray of objects
Documents and files to attach.
Fields of each item (5)
- typestringrequired
  A PDF YoPrint makes: the order or quote (order, order_compact), all jobs with or without mockups, all invoices (so_invoices, so_compact_invoices) or one invoice (single_compact_invoice, with options.id). Or a file: media or reference_media, with media_id. On a quote, the invoice files are named "Pro Forma Invoice" by default.
  - One of: "order", "order_compact", "so_jobs_with_mockup", "so_jobs_without_mockup", "so_invoices", "so_compact_invoices", "single_compact_invoice", "media", "reference_media"
- detailstring
- media_idstring
  The file's id. Required for media and reference_media.
- namestring
  The attachment's file name.
- optionsobject
  Child fields (2)
  - idstring
    For single_compact_invoice: the id of one of this order's invoices. Another order's invoice, or an invoice that can't be printed yet, is left out without an error, and the message is still sent.
  - show_mockupboolean
    For so_jobs_with_mockup and so_jobs_without_mockup: true puts each job's mockup pages in the job sheets, false leaves them out. It overrides the type's own choice. Text such as "true" or "off" is accepted too; any other value is refused with 422 validation_failed. Other types ignore it.
send_as_text_messageboolean
true to send it as a text message (SMS) instead of email.

Response

200Successful response.

dataobjectrequired
A message.
Child fields (16)
- idstringrequired
- actor_namestring | null
  The writer's name, by actor_type: the team member, contact, customer, guest, participant or vendor; the team's name for system. Null when it can't be found.
- actor_typestring | null
  Who wrote it: user (a team member), contact, customer, guest, participant, vendor or system.
- contact_idstring | null
  The contact who sent it, for replies.
- created_atstring (date-time) | null
  Sent. ISO 8601 with offset, or null.
- delivery_summaryobject | null
  Delivery state per recipient.
- emailstring | null
- messagestring | null
  The full message.
- namestring | null
  Sender name, for replies from the customer; null on messages your team sends (read actor_name).
- order_idstring | null
- order_scoped_idstring | null
- preview_messagestring | null
  The first 200 characters. An email's preview keeps its HTML.
- retryableboolean
  true when a failed delivery can be retried.
- statusstring | null
- typestring | null
- user_idstring | null
  The team member who sent it.
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 role can't message this order's customer.
Fix
Ask the team owner for message permission.
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.
422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
When
An empty participants list, a participant who can't receive the channel, a draft or deleted order, or the team's email limit is reached.
Fix
Add participants with an email address or SMS consent, or publish the order.
When
A participant id is not a current participant of this order: another order's participant, a removed one, or an unknown id (error.code participant_not_on_record). Nothing is saved or sent.
Fix
List this order's participants and send only their ids; add anyone missing as a participant first.
When
The team can't send email: email_feature_not_enabled_in_trial, or over the daily limit.
Fix
Ask YoPrint support to turn email on, or lift the block.

Notes

Ask before sending on someone's behalf: the customer receives it at once.

POSTAdd a participant to an order/v1/api/store/{team_slug}/sales_order/{hash_id}/participant
GETList the messages of an order/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/message
GETGet a message/v2/api/store/{team_slug}/messages/{hash_id}

Example request

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/message' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "internal_attachments": [      {        "type": "order"      }    ],    "message": "<p>Hi Alex, your order is ready for pickup.</p>",    "participants": [      {        "id": "LBbXMRNWVof2bd"      }    ]  }'

Example response 200

{
  "data": {
    "actor_name": "Alex Rivera",
    "actor_type": "user",
    "contact_id": null,
    "created_at": "2026-11-03T09:00:00+00:00",
    "email": null,
    "id": "mD1A7NR38PtyNs",
    "message": "<p>Hi Alex, your order is ready for pickup.</p>",
    "name": null,
    "order_id": "V4keXwwxMQyXw7",
    "order_scoped_id": "SO1001",
    "preview_message": "<p>Hi Alex, your order is ready for pickup.</p>",
    "retryable": false,
    "status": "pending",
    "type": "outbound",
    "user_id": "PydH0WtBhSeiNU"
  },
  "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