Send a message to the customer (v1)

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

v1Legacy · deprecatedOperation ID v1_public_sales_order_v1_message_store

Legacy (deprecated)

A newer operation does this better.Use Send a message to the customer (POST /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/message) instead.

Its answers say so in the Deprecation and X-YoPrint-Successor headers; see Deprecated operations.

Sends a message like the v2 operation, with the same body, but it also accepts drafts. Prefer Send a message to the customer (v2). 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. {hash_id} is the order's id (for example V4keXwwxMQyXw7); the ord_ unique key is not accepted here.

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

• 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 deleted order, or the team's email limit is reached.

  Fix

  Add participants with an email address or SMS consent.

  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.

Related

• POSTSend a message to the customer/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/message

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/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

Response

{
  "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
}