The Inbox holds the messages shoppers send through the storefront contact form, kept until the merchant deletes them. Reads require read_customers; moving, marking read or unread, and deleting require write_customers. Responses include the sender's email and phone; treat them as customer data.
Each entry is a conversation with its messages (read one to get them; the list carries last_message_preview). status is open (the Inbox), archived or spam. Moving a conversation to spam puts the sender's email and IP address on the store's block list for the contact form; moving it out of spam takes them off again. Spam is deleted automatically spam_delete_days after it got that status, and deletes_at says when. Reading through the API never marks a message read.
Messages the store's spam checks hold back are kept as spam and send neither the contact_messages/create webhook nor the merchant's email. Read page sizes and bulk caps from /inbox/conversations/limits; bulk changes apply atomically, and an id missing from the store changes none.
Endpoints#
Inbox limits
Fetch Inbox limits.
Returns pagination, search and bulk limits, and spam_delete_days. status_options lists each status value with its English display label.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
List inbox messages
List Inbox messages.
Returns the store's Inbox, most recent message first. Filter by status (default open) or to unread messages, or search name, email and subject. List entries carry the latest message's preview, not the full text; get one for its messages.
Query parameters
| Name | Type | Description |
|---|---|---|
cursor
|
string |
Use next_cursor from the previous page with unchanged filters. Invalid or stale cursors return INVALID_INPUT on cursor; restart from the first page. |
limit
|
integer |
Page size, 1 to 100 ( |
search
|
string |
Search name, email or subject. |
status
|
string |
open (default), archived or spam.
Allowed values
openarchivedspam |
unread
|
boolean |
true lists only unread messages in the Inbox. |
channel
|
string |
Only conversations from these channels, comma separated: email (also covers contact-form messages), instagram, messenger, live_chat.
Allowed values
emailinstagrammessengerlive_chat |
sender
|
string |
customer: only conversations linked to a customer; guest: only those that are not.
Allowed values
customerguest |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400VALIDATION_LIST_INVALID_LIMITLimit is not between 1 and
list_max_limit. -
400INVALID_INPUTcursoris invalid or stale (restart from the first page), orchannelorsenderholds an unknown value. -
400INBOX_SEARCH_TOO_LONGSearch exceeds the contract maximum.
-
400INBOX_STATUS_INVALIDStatus is not open, archived or spam.
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
Get Inbox counts
Fetch counts by status.
Returns how many messages are unread, open, archived and in spam.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Get a inbox message
Fetch one Inbox message with its full text.
Returns the conversation and its messages, oldest first. Reading through the API does not mark it as read.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Inbox message id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400INBOX_CONVERSATION_ID_INVALIDMessage id is not a valid UUID.
-
404NOT_FOUNDMessage does not exist in this store.
Get a inbox message's context
Fetch who wrote a message and the orders it is about.
Returns the store's customer behind the conversation (linked, or found by the sender's email) with their orders count, lifetime spend, tags and note; mentions: order numbers, email addresses and phone numbers the customer wrote in their messages; orders: up to 5 orders, newest first, found by the customer, the sender's email and phone, and those mentions (guest orders included), each with matched_by (customer, email, phone, number) and tracking (number, url, carrier); and up to 5 of the same person's other conversations. orders is null without the read_orders scope.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Inbox message id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400INBOX_CONVERSATION_ID_INVALIDMessage id is not a valid UUID.
-
404NOT_FOUNDMessage does not exist in this store.
Update a inbox message
Move a message or mark it read or unread.
Sets status (open, archived or spam) and/or read. Moving a message to spam puts its sender's email and IP on the store's block list for the contact form; moving it out of spam takes them off again.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Inbox message id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
status
|
string |
open, archived or spam. |
read
|
boolean |
true marks it read, false unread. |
Errors
-
400INBOX_CONVERSATION_ID_INVALIDMessage id is not a valid UUID.
-
404NOT_FOUNDMessage does not exist in this store.
-
400STORE_API_INVALID_REQUEST_BODYRequest body is not a JSON object, or has neither status nor read.
-
400INBOX_STATUS_INVALIDStatus is not open, archived or spam.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Bulk update inbox messages
Move several messages or mark them read or unread.
Updates every selected message atomically. If an id is invalid, missing or belongs to another store, none are changed.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
ids
required
|
array<uuid> |
Message ids, up to 100 ( |
status
|
string |
open, archived or spam. |
read
|
boolean |
true marks them read, false unread. |
Errors
-
400STORE_API_INVALID_REQUEST_BODYRequest body is not a JSON object.
-
400INBOX_CONVERSATION_ID_INVALIDAn id in
idsis not a valid UUID. -
400INBOX_BULK_NO_IDSNo ids were provided.
-
400INBOX_BULK_TOO_MANYBatch exceeds
bulk_max_items. -
400INBOX_STATUS_INVALIDStatus is not open, archived or spam.
-
404NOT_FOUNDOne or more messages do not exist in this store.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Reply to a inbox message
Send a reply to a message.
Sends body to the customer and adds it to the conversation as an outbound message. Instagram and Messenger conversations are answered through the store's connected Instagram account or Facebook Page: Meta allows replies within 7 days of the customer's last message (reply_window_ends_at), and after 24 hours the reply is sent with Meta's human agent tag. Email and contact-form conversations are answered by email from the store's sending address, in the same thread; customers' replies come back to the conversation through the store's Inbox address (see the Inbox email settings). can_reply says whether a reply can be sent now.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Inbox message id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
body
|
string |
The reply, plain text, up to 1000 characters ( |
attachments
|
array<object> |
Files from Upload an Inbox attachment, each {key, filename, content_type, size}. Email: at most 10 files and 10 MB in total. Instagram and Messenger: at most 5 files, each sent as its own message after |
Errors
-
400INBOX_CONVERSATION_ID_INVALIDMessage id is not a valid UUID.
-
404NOT_FOUNDMessage does not exist in this store.
-
400STORE_API_INVALID_REQUEST_BODYRequest body is not a JSON object.
-
400INBOX_REPLY_BODY_REQUIREDNeither
bodynorattachmentswas sent. -
400INBOX_REPLY_TOO_LONGbodyexceedsreply_max_length. -
400INBOX_REPLY_UNSUPPORTEDThe conversation cannot be answered from Tringify.
-
409INBOX_EMAIL_SENDER_MISSINGEmail conversation: the store has no sending address yet.
-
400INBOX_ATTACHMENT_UNSUPPORTEDattachmentson a conversation that cannot take files. -
400INBOX_ATTACHMENT_TYPEInstagram conversation: Instagram does not take this file type.
-
502INBOX_ATTACHMENT_PARTLY_SENTInstagram or Messenger: Meta took part of the reply; what was sent is in the conversation.
-
400INBOX_ATTACHMENT_INVALIDAn attachment is not one uploaded for this store, or its file is missing.
-
400INBOX_ATTACHMENT_TOO_MANYToo many attachments.
-
400INBOX_ATTACHMENT_TOO_LARGEAttachments are over the size limit.
-
502INBOX_EMAIL_SEND_FAILEDEmail conversation: the email was not accepted for sending; nothing was added to the conversation.
-
409INBOX_REPLY_WINDOW_CLOSEDMeta's reply window for this conversation has closed.
-
409SOCIAL_META_NOT_CONNECTEDInstagram and Facebook are not connected to the store.
-
409SOCIAL_META_RECONNECT_REQUIREDMeta no longer accepts the store's connection; the merchant must reconnect in Store Admin.
-
502SOCIAL_META_REQUEST_FAILEDMeta did not accept or answer the request; nothing was added to the conversation.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Create a inbox message
Email a customer from the Inbox.
Starts a new email conversation: sends body with subject to to from the store's sending address and keeps it in the Inbox. The customer's replies come back to the same conversation through the store's Inbox address. When the address belongs to a customer of the store, the conversation is linked to them.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
to
required
|
string |
The customer's email address, up to 320 characters. |
name
|
string |
The customer's name, shown in the Inbox, up to 255 characters. |
subject
required
|
string |
Subject, up to 255 characters. |
body
required
|
string |
The message, plain text, up to 5000 characters. |
attachments
|
array<object> |
Files from Upload an Inbox attachment, each {key, filename, content_type, size}; at most 10 files and 10 MB in total. |
Errors
-
503INBOX_EMAIL_UNAVAILABLEThe Inbox address could not be created right now; try again.
-
400STORE_API_INVALID_REQUEST_BODYRequest body is not a JSON object.
-
400INBOX_COMPOSE_RECIPIENT_REQUIREDtois missing. -
400INBOX_COMPOSE_RECIPIENT_INVALIDtois not a valid email address. -
400INBOX_COMPOSE_NAME_TOO_LONGnameis too long. -
400INBOX_COMPOSE_SUBJECT_REQUIREDsubjectis missing. -
400INBOX_COMPOSE_SUBJECT_TOO_LONGsubjectis too long. -
400INBOX_REPLY_BODY_REQUIREDbodyis missing or empty. -
400INBOX_COMPOSE_BODY_TOO_LONGbodyis too long. -
409INBOX_EMAIL_SENDER_MISSINGThe store has no sending address yet.
-
400INBOX_ATTACHMENT_INVALIDAn attachment is not one uploaded for this store, or its file is missing.
-
400INBOX_ATTACHMENT_TOO_MANYToo many attachments.
-
400INBOX_ATTACHMENT_TOO_LARGEAttachments are over the size limit.
-
502INBOX_EMAIL_SEND_FAILEDThe email was not accepted for sending; nothing was kept.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Upload an Inbox attachment
Get a link to upload a file for a reply or new message.
Returns upload_url, valid for 30 minutes: PUT the file's bytes to it with its Content-Type. Then pass the returned attachment in attachments when replying or creating a message. Email files are at most 10 MB each and in total per email; with channel instagram or messenger a file can be up to 25 MB (photos 8 MB), and Instagram takes only JPEG and PNG photos, videos, audio and PDFs.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
filename
required
|
string |
The file's name. |
content_type
|
string |
The file's media type. |
size
required
|
integer |
The file's size in bytes. |
channel
|
string |
The conversation's channel when the file is for an Instagram or Messenger reply: instagram or messenger. Omit it for email. |
Errors
-
400STORE_API_INVALID_REQUEST_BODYRequest body is not a JSON object.
-
400INBOX_ATTACHMENT_INVALIDfilenameis missing orsizeis not a positive number. -
400INBOX_ATTACHMENT_TOO_LARGEsizeis over the limit. -
400INBOX_ATTACHMENT_TYPEchannelis instagram and Instagram does not take this file type. -
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Get Inbox email settings
Fetch the store's Inbox email address.
Returns the store's Inbox address (on inbox.tringify.com), which the store's support mailbox forwards to so customers' emails land in the Inbox, reply_to_mode (own: customers' replies go to the store's support address; inbox: straight to the Inbox address), the store's support address (support_address, set in the email settings) and when the last email arrived. The address is created on first use.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
503INBOX_EMAIL_UNAVAILABLEThe Inbox address could not be created right now; try again.
Update Inbox email settings
Choose where customers' replies go, or change the address.
Sets reply_to_mode, or with change_address true gives the store a new Inbox address (the old one stops receiving email at once, so the forwarding must be updated).
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
reply_to_mode
|
string |
own or inbox. |
change_address
|
boolean |
true gives the store a new Inbox address. |
forwarded_only
|
boolean |
true accepts only email that came through the store's support address; anything else goes to spam. Replies to emails sent from the Inbox are always accepted. |
Errors
-
503INBOX_EMAIL_UNAVAILABLEThe Inbox address could not be created right now; try again.
-
400STORE_API_INVALID_REQUEST_BODYRequest body is not a JSON object.
-
400INBOX_EMAIL_REPLY_TO_INVALIDreply_to_modeis not own or inbox. -
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Delete a inbox message
Permanently delete one message.
Deletes the conversation and all its messages. This cannot be undone.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Inbox message id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400INBOX_CONVERSATION_ID_INVALIDMessage id is not a valid UUID.
-
404NOT_FOUNDMessage does not exist in this store.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects).
Bulk delete inbox messages
Permanently delete several messages.
Deletes every selected message atomically. If an id is invalid, missing or belongs to another store, none are deleted.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
ids
required
|
array<uuid> |
Message ids, up to 100 ( |
Errors
-
400STORE_API_INVALID_REQUEST_BODYRequest body is not a JSON object.
-
400INBOX_CONVERSATION_ID_INVALIDAn id in
idsis not a valid UUID. -
400INBOX_BULK_NO_IDSNo ids were provided.
-
400INBOX_BULK_TOO_MANYBatch exceeds
bulk_max_items. -
400INBOX_STATUS_INVALIDStatus is not open, archived or spam.
-
404NOT_FOUNDOne or more messages do not exist in this store.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Fields#
Field |
Type |
Create |
Update |
Required |
Translatable |
|---|---|---|---|---|---|
|
select |
Yes |
No |
No |
|
|
boolean |
No |
No |
No |
|
|
datetime |
No |
No |
No |
|
|
text |
No |
No |
No |
|
|
text |
No |
No |
No |
|
|
text |
No |
No |
No |
|
|
text |
Yes |
No |
create |
No |
|
text |
No |
No |
No |
|
|
id |
No |
No |
No |
|
|
select |
No |
Yes |
No |
|
|
boolean |
No |
Yes |
No |
|
|
datetime |
No |
No |
No |
|
|
datetime |
No |
No |
No |
|
|
datetime |
No |
No |
No |
Webhook events#
Subscribe to these events to keep your integration in sync with inbox messages. Each event shows the required Store API scope and store permission, the available payload fields, and an example payload. Subscription setup is validated against those permissions; delivery is always restricted to the subscription's store.
Contact message received
Fired when a shopper sends the storefront contact form and the message lands in the store's Inbox. Messages the store's spam checks hold back are kept as spam in the Inbox and do not fire it.
Payload fields
| Field | Type | Description |
|---|---|---|
contact_message |
object |
Always present |
contact_message.id |
string |
Always present |
contact_message.storefront_id |
string | null |
Selectable in the Payload builder |
contact_message.customer_id |
string | null |
Selectable in the Payload builder |
contact_message.name |
string |
Always present |
contact_message.email |
string |
Always present |
contact_message.phone |
string |
Always present |
contact_message.subject |
string |
Always present |
contact_message.body |
string |
Always present |
contact_message.created_at |
string |
Always present |
Direct message received
Fired when a customer's message lands in the store's Inbox: an Instagram or Messenger message to the store's connected Instagram account or Facebook Page, or an email the store's support mailbox forwards to its Inbox address. channel is instagram, messenger or email; sender_id is the customer's id scoped to that account, or their email address. Attachments are not included.
Payload fields
| Field | Type | Description |
|---|---|---|
direct_message |
object |
Always present |
direct_message.conversation_id |
string |
Always present |
direct_message.message_id |
string |
Always present |
direct_message.channel |
string |
Always present |
direct_message.sender_id |
string |
Always present |
direct_message.sender_name |
string |
Always present |
direct_message.body |
string |
Always present |
direct_message.created_at |
string |
Always present |