Inbox

Read, move, delete and subscribe to inbox messages: the messages shoppers send through the storefront contact form.

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

GET read_customers

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

GET read_customers

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 (list_max_limit from the limits). Default 20.

Example: 20
search string

Search name, email or subject.

Example: order
status string

open (default), archived or spam.

Allowed values
openarchivedspam
Example: open
unread boolean

true lists only unread messages in the Inbox.

Example: true
channel string

Only conversations from these channels, comma separated: email (also covers contact-form messages), instagram, messenger, live_chat.

Allowed values
emailinstagrammessengerlive_chat
Example: instagram,messenger
sender string

customer: only conversations linked to a customer; guest: only those that are not.

Allowed values
customerguest
Example: customer

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 VALIDATION_LIST_INVALID_LIMIT

    Limit is not between 1 and list_max_limit.

  • 400 INVALID_INPUT

    cursor is invalid or stale (restart from the first page), or channel or sender holds an unknown value.

  • 400 INBOX_SEARCH_TOO_LONG

    Search exceeds the contract maximum.

  • 400 INBOX_STATUS_INVALID

    Status is not open, archived or spam.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

Get Inbox counts

GET read_customers

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

GET read_customers

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.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 INBOX_CONVERSATION_ID_INVALID

    Message id is not a valid UUID.

  • 404 NOT_FOUND

    Message does not exist in this store.

Get a inbox message's context

GET read_customers

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.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 INBOX_CONVERSATION_ID_INVALID

    Message id is not a valid UUID.

  • 404 NOT_FOUND

    Message does not exist in this store.

Update a inbox message

PUT write_customers

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.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
status string

open, archived or spam.

Example: archived
read boolean

true marks it read, false unread.

Example: true

Errors

  • 400 INBOX_CONVERSATION_ID_INVALID

    Message id is not a valid UUID.

  • 404 NOT_FOUND

    Message does not exist in this store.

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not a JSON object, or has neither status nor read.

  • 400 INBOX_STATUS_INVALID

    Status is not open, archived or spam.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Bulk update inbox messages

POST write_customers

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 (bulk_max_items from the limits).

Example: ["0b8f6a52-3c1e-4d7a-9f2b-6e5d4c3b2a19"]
status string

open, archived or spam.

Example: archived
read boolean

true marks them read, false unread.

Example: true

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not a JSON object.

  • 400 INBOX_CONVERSATION_ID_INVALID

    An id in ids is not a valid UUID.

  • 400 INBOX_BULK_NO_IDS

    No ids were provided.

  • 400 INBOX_BULK_TOO_MANY

    Batch exceeds bulk_max_items.

  • 400 INBOX_STATUS_INVALID

    Status is not open, archived or spam.

  • 404 NOT_FOUND

    One or more messages do not exist in this store.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Reply to a inbox message

POST write_customers

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.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

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 (reply_max_length from the limits) for Instagram and Messenger, 5000 for email. Required unless attachments are sent.

Example: Yes, it is back in stock in every size.
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 body, up to 25 MB each (photos 8 MB); Instagram takes JPEG and PNG photos, videos, audio and PDFs.

Example: [{"key":"f192d1f9-b01f-48c2-9300-3f3bf14716b0/uploads/6a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d/invoice.pdf","filename":"invoice.pdf","content_type":"application/pdf","size":48213}]

Errors

  • 400 INBOX_CONVERSATION_ID_INVALID

    Message id is not a valid UUID.

  • 404 NOT_FOUND

    Message does not exist in this store.

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not a JSON object.

  • 400 INBOX_REPLY_BODY_REQUIRED

    Neither body nor attachments was sent.

  • 400 INBOX_REPLY_TOO_LONG

    body exceeds reply_max_length.

  • 400 INBOX_REPLY_UNSUPPORTED

    The conversation cannot be answered from Tringify.

  • 409 INBOX_EMAIL_SENDER_MISSING

    Email conversation: the store has no sending address yet.

  • 400 INBOX_ATTACHMENT_UNSUPPORTED

    attachments on a conversation that cannot take files.

  • 400 INBOX_ATTACHMENT_TYPE

    Instagram conversation: Instagram does not take this file type.

  • 502 INBOX_ATTACHMENT_PARTLY_SENT

    Instagram or Messenger: Meta took part of the reply; what was sent is in the conversation.

  • 400 INBOX_ATTACHMENT_INVALID

    An attachment is not one uploaded for this store, or its file is missing.

  • 400 INBOX_ATTACHMENT_TOO_MANY

    Too many attachments.

  • 400 INBOX_ATTACHMENT_TOO_LARGE

    Attachments are over the size limit.

  • 502 INBOX_EMAIL_SEND_FAILED

    Email conversation: the email was not accepted for sending; nothing was added to the conversation.

  • 409 INBOX_REPLY_WINDOW_CLOSED

    Meta's reply window for this conversation has closed.

  • 409 SOCIAL_META_NOT_CONNECTED

    Instagram and Facebook are not connected to the store.

  • 409 SOCIAL_META_RECONNECT_REQUIRED

    Meta no longer accepts the store's connection; the merchant must reconnect in Store Admin.

  • 502 SOCIAL_META_REQUEST_FAILED

    Meta did not accept or answer the request; nothing was added to the conversation.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Create a inbox message

POST write_customers

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.

Example: avery@example.com
name string

The customer's name, shown in the Inbox, up to 255 characters.

Example: Avery Stone
subject required string

Subject, up to 255 characters.

Example: Your order is ready
body required string

The message, plain text, up to 5000 characters.

Example: Hi Avery, your order is ready to pick up.
attachments array<object>

Files from Upload an Inbox attachment, each {key, filename, content_type, size}; at most 10 files and 10 MB in total.

Example: [{"key":"f192d1f9-b01f-48c2-9300-3f3bf14716b0/uploads/6a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d/invoice.pdf","filename":"invoice.pdf","content_type":"application/pdf","size":48213}]

Errors

  • 503 INBOX_EMAIL_UNAVAILABLE

    The Inbox address could not be created right now; try again.

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not a JSON object.

  • 400 INBOX_COMPOSE_RECIPIENT_REQUIRED

    to is missing.

  • 400 INBOX_COMPOSE_RECIPIENT_INVALID

    to is not a valid email address.

  • 400 INBOX_COMPOSE_NAME_TOO_LONG

    name is too long.

  • 400 INBOX_COMPOSE_SUBJECT_REQUIRED

    subject is missing.

  • 400 INBOX_COMPOSE_SUBJECT_TOO_LONG

    subject is too long.

  • 400 INBOX_REPLY_BODY_REQUIRED

    body is missing or empty.

  • 400 INBOX_COMPOSE_BODY_TOO_LONG

    body is too long.

  • 409 INBOX_EMAIL_SENDER_MISSING

    The store has no sending address yet.

  • 400 INBOX_ATTACHMENT_INVALID

    An attachment is not one uploaded for this store, or its file is missing.

  • 400 INBOX_ATTACHMENT_TOO_MANY

    Too many attachments.

  • 400 INBOX_ATTACHMENT_TOO_LARGE

    Attachments are over the size limit.

  • 502 INBOX_EMAIL_SEND_FAILED

    The email was not accepted for sending; nothing was kept.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Upload an Inbox attachment

POST write_customers

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.

Example: invoice.pdf
content_type string

The file's media type.

Example: application/pdf
size required integer

The file's size in bytes.

Example: 48213
channel string

The conversation's channel when the file is for an Instagram or Messenger reply: instagram or messenger. Omit it for email.

Example: instagram

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not a JSON object.

  • 400 INBOX_ATTACHMENT_INVALID

    filename is missing or size is not a positive number.

  • 400 INBOX_ATTACHMENT_TOO_LARGE

    size is over the limit.

  • 400 INBOX_ATTACHMENT_TYPE

    channel is instagram and Instagram does not take this file type.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Get Inbox email settings

GET read_customers

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

  • 503 INBOX_EMAIL_UNAVAILABLE

    The Inbox address could not be created right now; try again.

Update Inbox email settings

PUT write_customers

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.

Example: own
change_address boolean

true gives the store a new Inbox address.

Example: false
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.

Example: false

Errors

  • 503 INBOX_EMAIL_UNAVAILABLE

    The Inbox address could not be created right now; try again.

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not a JSON object.

  • 400 INBOX_EMAIL_REPLY_TO_INVALID

    reply_to_mode is not own or inbox.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Delete a inbox message

DELETE write_customers

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.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 INBOX_CONVERSATION_ID_INVALID

    Message id is not a valid UUID.

  • 404 NOT_FOUND

    Message does not exist in this store.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

Bulk delete inbox messages

POST write_customers

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 (bulk_max_items from the limits).

Example: ["0b8f6a52-3c1e-4d7a-9f2b-6e5d4c3b2a19"]

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not a JSON object.

  • 400 INBOX_CONVERSATION_ID_INVALID

    An id in ids is not a valid UUID.

  • 400 INBOX_BULK_NO_IDS

    No ids were provided.

  • 400 INBOX_BULK_TOO_MANY

    Batch exceeds bulk_max_items.

  • 400 INBOX_STATUS_INVALID

    Status is not open, archived or spam.

  • 404 NOT_FOUND

    One or more messages do not exist in this store.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Fields#

Field

Type

Create

Update

Required

Translatable

channel

select

Yes

No

No

can_reply

boolean

No

No

No

reply_window_ends_at

datetime

No

No

No

contact_name

text

No

No

No

contact_email

text

No

No

No

contact_phone

text

No

No

No

subject

text

Yes

No

create

No

last_message_preview

text

No

No

No

customer_id

id

No

No

No

status

select

No

Yes

No

read

boolean

No

Yes

No

last_message_at

datetime

No

No

No

created_at

datetime

No

No

No

deletes_at

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

EVENT contact_messages/create App scope: read_customers Staff permission: customers:read

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

EVENT direct_messages/create App scope: read_customers Staff permission: customers:read

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