Receive support mail, keep conversations together, and send replies.
This guide gives help@inbound.support.example.com an inbox, replies from help@support.example.com, keeps later mail on plus-addresses such as help+ticket_123@inbound.support.example.com, and watches those replies on a delivery webhook. You keep a mailbox, a ticket, and a message in your own database.
Before you start
A Full access key from API keys for the setup steps. Run them from your shell, not the desk.
A Send only key for the desk's reply path in step 5.
DNS for support.example.com. You will publish DKIM, return-path, and MX on inbound.support.example.com. Leave the sending domain MX alone.
A payment method on the team. Cluster create returns 403{error: payment_required} when billing is on and there is no card.
If sending_ready is still false, GET /api/v1/clusters/NmQpXr again. If the response is 403kyc_required, the team is still pending. While the team is pending, you send only to member emails, live inbox addresses, and inbox forward-to addresses, and anything else returns 403kyc_required. See Does PostShiba require production approval?.
2. Add the sending domain
Create and verify support.example.com before the inbox. The same domain lets agents reply from help@support.example.com.
Save webhook_secret now. Lists omit it. Publish the MX record on inbound.support.example.com. Leave support.example.com MX alone. See How do I avoid MX conflicts?.
A 2xx response marks the delivery as sent. Return 204 on success. A bad signature should return 401. saveMessage must upsert on the PostShiba message ID. If queue publication fails, let the request fail so PostShiba retries. See Verify webhook requests and Inbound messages.
For a new message to the base inbox, create a ticket. For later mail, read thread_id. PostShiba sets that field from the plus tag first, then In-Reply-To, then References, then Message-ID. See Get email content.
5. Send an agent reply
Cluster create already issues a default SMTP credential. REST sends use the Bearer token. Create another credential only when you need the password for SMTP.
Pass the Send only key as apiKey. The desk gets inbound mail from the webhook in step 4, so it never needs to read messages through the API. If you later fetch messages or events from the desk, that call needs a Full access key. Keep both keys on your server, never in the agent's browser.
Set reply_to to a plus-address with your ticket ID. Set In-Reply-To and References from the inbound headers.
1{2 "queued": true,3 "message_id": "abc@postshiba.com",4 "from": "Acme Support <help@support.example.com>",5 "to": ["you@example.com"],6 "subject": "Re: I need help with order 123",7 "unique_args": {8 "ticket_id": "ticket_123",9 "support_message_id": "msg_1"10 }11}
When the customer replies, mail goes to help+ticket_123@inbound.support.example.com. PostShiba matches it to the help inbox and sets thread_id to ticket_123. If inject queued nobody, the response is 502{error: inject_failed}.
6. Track the reply
Create a separate webhook endpoint for outgoing delivery events.
Match ticket_id and support_message_id from the flattened unique args. A delivered event means the destination accepted the reply. See Delivered but not in the inbox.
You now have a verified support.example.com, a domain-bound inbox, a signed inbound handler, a plus-address reply, and a delivery webhook.
When to move to dedicated IPs
Support replies are low volume and conversational, so the cluster's shared IPs are usually the right call. Consider a dedicated IP in a transactional pool when you send a steady tens of thousands of messages a month, need a fixed IP a customer can allowlist, or want reputation apart from other senders. Never put replies in a bulk pool. A new dedicated IP warms up for 14 days; overflow keeps replies flowing on shared IPs meanwhile. When you opt in, add "X-Capsule-Pool": "support" to the headers object in send-reply.js. See Set up IP pools and warm up dedicated IPs.
