Inbox

The store inbox holds every conversation a shopper has with your store: the chat on your site, where your store’s assistant answers first, and email. A reply to an order email lands in that order’s conversation. Anything the assistant can’t answer, and anyone who asks for a person, waits for your team under Needs you.

1. Shopper writesin the chat or by email
2. Needs youthe assistant hands over
3. You replyby email or in the chat
4. Waitingfor the shopper's answer

1. List what needs you

curl -sS "https://api.tuppence.ai/v1/store_threads?status=needs_you" \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY"

GET /v1/store_threads/{id} returns one conversation with its messages.

2. Reply as your store

curl -sS https://api.tuppence.ai/v1/store_threads/sthr_…/messages \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d text="It's on its way and should arrive on Thursday."

The reply goes by email when the shopper left an address, from your store’s sender (your own domain once it is verified), and in the chat otherwise. The conversation then waits for the shopper.

3. Close it, or give it back

POST /v1/store_threads/{id} with status: closed, or status: open to let your store’s assistant answer again.

Statuses

status	Means
open	Your store’s assistant is answering
needs_you	Waiting for your team. needs_you_reason says why
waiting_customer	You answered; waiting for the shopper
closed	Done. A new message opens it again

Your sending domain

Store emails go from Tuppence in your name until your own domain is verified. In Store settings › Email, add mail. on your domain (a subdomain, so your own email is untouched) and put its three records at your DNS host. Tuppence checks them every 10 minutes for 72 hours and names any record that is missing or wrong. A new domain sends up to 500 emails a day in its first week, doubling each week.

Route	Does
GET /v1/merchant_sending_domains	Your sending domain, with each record and what the last check found
POST /v1/merchant_sending_domains	Adds one (domain, or the suggestion when left out)
POST /v1/merchant_sending_domains/{id}/check	Checks the records now

Events

Event	When
store_thread.message_received	A shopper wrote
store_thread.needs_you	A conversation went to your team
merchant_sending_domain.verified	Your store’s emails now go from your own domain

Over MCP and the assistant

Tool	Scope	Does
list_store_threads, get_store_thread	customers:read	Conversations and their messages
reply_to_store_thread	customers:write	Answers a shopper. A person approves every answer
update_store_thread	customers:write	Closes a conversation or gives it back to the assistant
get_store_email_sender	sites:read	Where your store’s emails come from. Adding a domain is yours, in the dashboard

Next

• Reviews
• Orders