Filter messages

POST/v2/api/store/{team_slug}/messages/filter

v2Operation ID v2_public_messages_filter

Lists messages like GET /v2/api/store/{team_slug}/messages, narrowed by direction or status, with an optional sort. For example, replies that still have no status: type in ["inbound"] and is_status_null eq true.

Each filter is {key, operator, value}. Several filters must all match. Send page in the body or the query string.

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.

Business rules

filters is optional. If you send it, it can't be empty. Leaving it out returns every message you can see. Keys: type, status, status_id, is_status_null.
For type, status and status_id, value is a list and operator is in or nin. For is_status_null, value is true or false (JSON booleans) and operator is eq or neq.
Values of type and status are not checked: a word no message has just matches nothing.
Sort keys: id, order_id, purchase_order_id, type, actor_type, created_at, status.

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team

Request body

application/json, optional.

filtersarray of objects
- At least 1 item
Fields of each item (3)
- keystringrequired
  type: outbound or inbound. status: the older delivery status word (delivered, delivery_failed, received, ...). status_id: your team's message status ids. is_status_null: whether a status is set.
  - One of: "type", "status", "status_id", "is_status_null"
- operatorstringrequired
  in or nin with a list, for type, status and status_id. eq (or neq, which is accepted and acts the same) with true or false, for is_status_null.
  - One of: "in", "nin", "eq", "neq"
- valuearray | booleanrequired
pageinteger
- Minimum 1
sortarray of objects
Fields of each item (2)
- directionstringrequired
  - One of: "asc", "desc"
- keystringrequired
  - One of: "id", "order_id", "purchase_order_id", "type", "actor_type", "created_at", "status"

Response

200Successful response.

dataarray of objectsrequired
Fields of each item (32)
- 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)
- customerobject | null
  The order's customer. Null without an order.
  Child fields (2)
  - idinteger
    A plain number, not a hash id; no operation takes it.
  - namestring
- 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
- emailstring | null
  The sender's email address.
- has_messageboolean
- has_original_messageboolean
- idstring
- is_order_rushinteger | null
  1 for a rush order, 0 otherwise (a number, not a boolean); null for a message without an order.
  - One of: 0, 1
- modestring | boolean
  The order's state in the web app: view once it is created, create while it is a draft, edit while someone is editing it. false (not null) without an order.
- 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. Null without an order.
- 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. An empty string "" (not 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).
- 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. The list sends their whole account profile; rely only on id, name, email, avatar_url and timezone, which the single message also has.
- user_idstring | null
- vendorobject | null
  The purchase order's vendor. Null without a purchase order.
  Child fields (2)
  - idinteger
    A plain number, not a hash id; no operation takes it.
  - namestring
statusintegerrequired
successbooleanrequired
paginationobject
Child fields (6)
- countintegerrequired
- currentPageintegerrequired
- linksobject | array of anyrequired
  Links to the neighbouring pages: previous and next, each present only when that page exists. An empty list, [], when there is only one page.
  Child fields (2)
  - nextstring (uri)
    The next page.
  - previousstring (uri)
    The previous page.
- perPageintegerrequired
- totalintegerrequired
- totalPagesintegerrequired

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.
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
filters is an empty list, or a key, operator or value is not allowed (validation_failed, with the problem under error.fields).
Fix
Use the keys and operators listed here, or leave filters out.

Notes

Without sort, the order of results is not defined. Send created_at desc when you page.
is_status_null only reads value: true finds messages without a status and false those with one, whatever the operator.
Get status_id values from your team's message statuses (GET /v1/api/store/{team_slug}/setting/status/customer_message).

GETList messages/v2/api/store/{team_slug}/messages
GETList message thread statuses/v1/api/store/{team_slug}/setting/status/customer_message

Example request

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/messages/filter' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "filters": [      {        "key": "type",        "operator": "in",        "value": [          "inbound"        ]      },      {        "key": "is_status_null",        "operator": "eq",        "value": true      }    ],    "sort": [      {        "direction": "desc",        "key": "created_at"      }    ]  }'

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",
      "customer": {
        "id": 2001,
        "name": "Northwind Apparel"
      },
      "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
      },
      "email": "alex@example.com",
      "has_message": true,
      "has_original_message": true,
      "id": "u7HKhdhT6tkEUy",
      "is_order_rush": 0,
      "mode": "view",
      "name": "Alex Rivera",
      "order_id": "V4keXwwxMQyXw7",
      "order_object_type": "sales_order",
      "order_quote": false,
      "order_scoped_id": "SO1001",
      "participant": null,
      "preview_message": "Your order is ready for pickup.",
      "purchase_order_id": null,
      "purchase_scoped_id": "",
      "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": [],
      "status": "delivery_failed",
      "status_id": null,
      "system": false,
      "type": "outbound",
      "user": {
        "avatar_url": "https://example.com/avatar.png",
        "email": "alex@example.com",
        "ga_id": "u1001",
        "has_affiliate_account": false,
        "hs_id": 1001,
        "id": "VG7s3tFzyQbO2N",
        "last_trial": null,
        "name": "Alex Rivera",
        "onboarded": true,
        "preference": null,
        "sso": false,
        "timezone": "America/New_York",
        "trial_used": false
      },
      "user_id": "VG7s3tFzyQbO2N",
      "vendor": null
    }
  ],
  "pagination": {
    "count": 1,
    "currentPage": 1,
    "links": [],
    "perPage": 50,
    "total": 1,
    "totalPages": 1
  },
  "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