Create a key to copy examples filled with your team.

Create an account Sign in

Build an AI agent inbox on PostShiba

Give an agent a real inbox with signed webhooks and reply support.

PostShiba receives and parses the mail. Your application decides what the agent may read, which model to call, and whether a reply is safe to send. Keep those responsibilities separate so untrusted mail cannot bypass your model and reply policies.

The setup in this guide uses a hosted PostShiba inbox. Hosted inboxes skip MX setup, but PostShiba only routes them after your approved team has an active shared-IP cluster. You also need a verified sending domain and tenant credential before the agent can reply.

Prepare the shared cluster

Create the cluster before you issue an inbox. Wait until its response reports sending_ready: true.

create-cluster.sh
1 export CAPSULE_URL="https://postshiba.com"
2 export CAPSULE_API_KEY="YOUR_API_KEY"
3 export TEAM_ID="1"
4
5 curl -sS \
6 --request POST \
7 --url "$CAPSULE_URL/api/v1/teams/$TEAM_ID/clusters" \
8 --header "Authorization: Bearer $CAPSULE_API_KEY" \
9 --header "Content-Type: application/json" \
10 --data '{
11 "cluster": {
12 "name": "agent-mail",
13 "size": "small",
14 "region": "manual"
15 }
16 }'

PostShiba must approve the team first. Cluster and inbox creation return 403 {"error":"kyc_required"} until then.

Pick an inbox model

Use one inbox per agent when agents have different owners, tools, or permissions. Each inbox has its own secret and can be disabled on its own.

Use one inbox with plus-addresses when every conversation shares the same trust boundary. For example, inbabc123+conversation_42@inbound.postshiba.com lands in the inbabc123 inbox and sets thread_id to conversation_42.

Tenants are the stronger boundary inside one PostShiba team. If your product serves several customers, create one tenant per customer and put that customer's domains, credentials, inboxes, and suppressions under it.

1. Create a tenant when you need isolation

You can skip this step for a single internal agent and use the team's default tenant.

create-tenant.sh
1 curl -sS \
2 --request POST \
3 --url "$CAPSULE_URL/api/v1/teams/$TEAM_ID/tenants" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY" \
5 --header "Content-Type: application/json" \
6 --data '{
7 "tenant": {
8 "name": "Acme agents",
9 "slug": "acme-agents"
10 }
11 }'

The shell examples share these variables. Run the exports in your current shell, or put them in setup.sh and load that file with source setup.sh.

Keep the returned tenant ID and slug. The ID provisions tenant-owned resources. The slug is convenient on send requests and appears as tenant_id in delivery webhook payloads.

2. Issue a hosted inbox

Your team must pass PostShiba's sender review before it can create an inbox. The API returns kyc_required until then.

Omit sending_domain_id and local_part. PostShiba generates an address on its inbound zone.

create-inbox.sh
1 curl -sS \
2 --request POST \
3 --url "$CAPSULE_URL/api/v1/teams/$TEAM_ID/inboxes" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY" \
5 --header "Content-Type: application/json" \
6 --data '{
7 "inbox": {
8 "name": "Acme research agent",
9 "tenant_id": 12,
10 "webhook_url": "https://agents.example.com/webhooks/capsule/inbound",
11 "webhook_format": "json"
12 }
13 }'

The result is ready to receive:

inbox-response.json
1 {
2 "id": 3,
3 "name": "Acme research agent",
4 "address": "inbabc123@inbound.postshiba.com",
5 "local_part": "inbabc123",
6 "host": "inbound.postshiba.com",
7 "tenant_id": 12,
8 "webhook_url": "https://agents.example.com/webhooks/capsule/inbound",
9 "webhook_format": "json",
10 "webhook_secret": "SAVE_THIS_SECRET",
11 "mx_status": "not_required",
12 "retention_hours": 168
13 }

Save the inbox ID, address, and webhook_secret with your agent record. PostShiba omits the secret from inbox lists.

Production webhook URLs must use HTTPS. Use a public address. At delivery, PostShiba rejects localhost, metadata.google.internal, IPv4 private and link-local ranges, and IPv6 loopback and link-local ranges.

3. Verify and store every webhook

An email is untrusted input. Verify the signature, reject stale timestamps, deduplicate on the inbound message ID, and copy the message into your database before a model sees it.

Do not run the model inside the webhook request. PostShiba's webhook client waits ten seconds for a response. A slow model call causes a retry and may run the same agent task twice.

inbound-webhook.js
1 import { createHmac, timingSafeEqual } from "node:crypto";
2
3 function verifyPostShiba({ rawBody, timestamp, signature, secret }) {
4 if (!timestamp || !signature?.startsWith("sha256=")) return false;
5
6 const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
7 if (!Number.isFinite(age) || age > 300) return false;
8
9 const expected = createHmac("sha256", secret)
10 .update(`${timestamp}.${rawBody}`)
11 .digest();
12 const received = Buffer.from(signature.slice(7), "hex");
13
14 return received.length === expected.length &&
15 timingSafeEqual(received, expected);
16 }
17
18 export function createAgentInboxHandler({ inbox, store, enqueueOnce }) {
19 return async function handle(request) {
20 const rawBody = await request.text();
21 const timestamp = request.headers.get("X-Capsule-Timestamp");
22 const signature = request.headers.get("X-Capsule-Signature");
23
24 if (!verifyPostShiba({
25 rawBody,
26 timestamp,
27 signature,
28 secret: inbox.webhookSecret,
29 })) {
30 return new Response("invalid signature", { status: 401 });
31 }
32
33 const message = JSON.parse(rawBody);
34 if (message.inbox_id !== inbox.capsuleId) {
35 return new Response("wrong inbox", { status: 403 });
36 }
37
38 // Upsert by PostShiba message ID so a retry cannot make a duplicate.
39 await store.upsertInbound({
40 id: message.id,
41 agentId: inbox.agentId,
42 from: message.from,
43 to: message.to,
44 subject: message.subject,
45 text: message.text,
46 html: message.html,
47 threadId: message.thread_id,
48 inReplyTo: message.in_reply_to,
49 headers: message.headers,
50 envelope: message.envelope,
51 attachments: message.attachments,
52 });
53
54 // Call this even after an upsert finds an existing row. If the first
55 // queue publish failed, PostShiba's retry gets another chance. The queue
56 // key must make a successful publish idempotent.
57 await enqueueOnce(`agent-inbound:${message.id}`, {
58 topic: "agent-inbound",
59 messageId: message.id,
60 });
61 return new Response(null, { status: 204 });
62 };
63 }

upsertInbound must use the PostShiba message ID as its unique key. enqueueOnce must keep a durable deduplication key. If queue publication fails, let the request fail so PostShiba can retry both safe steps.

The five-minute age limit is your receiver policy. PostShiba signs the timestamp but does not enforce a replay window for your application.

4. Put a safety step before the model

The email body can contain prompt injection, malicious links, or instructions to use tools. It should never become a system prompt.

After the policy check, pass only approved inputs to the model and either save or send its draft:

run-agent.js
1 export async function processAgentMail({
2 messageId,
3 store,
4 model,
5 policy,
6 sendReply,
7 }) {
8 const message = await store.getInbound(messageId);
9 const conversation = await store.findConversation({
10 agentId: message.agentId,
11 threadId: message.threadId,
12 });
13
14 const decision = await policy.inspect({
15 sender: message.from,
16 subject: message.subject,
17 text: message.text,
18 attachments: message.attachments.map(({ filename, content_type, size }) => ({
19 filename,
20 contentType: content_type,
21 size,
22 })),
23 });
24
25 if (!decision.mayRunAgent) {
26 await store.markNeedsReview(messageId, decision.reason);
27 return;
28 }
29
30 const draft = await model.draftReply({
31 trustedInstructions: conversation.agentInstructions,
32 untrustedEmail: {
33 from: message.from,
34 subject: message.subject,
35 text: message.text,
36 },
37 allowedTools: decision.allowedTools,
38 });
39
40 if (decision.requiresHumanApproval) {
41 await store.saveDraft(messageId, draft);
42 return;
43 }
44
45 await sendReply({ message, conversation, text: draft.text });
46 }

Your application owns policy and model. PostShiba neither runs agents nor inspects prompts. One inbox can feed a human approval queue, a read-only summarizer, or an agent with a limited set of tools.

Start with no automatic tool calls and human approval for replies. Add autonomy per sender or workflow after you have logs and failure handling.

5. Send the agent's reply

A hosted inbox receives mail, but it is not a sending identity. Verify a sending domain, create a shared cluster, and issue an SMTP credential for the tenant first. The transactional email guide shows those three setup calls. Adapt its domain and credential requests by setting tenant_id to this inbox's tenant.

create-domain.json
1 {
2 "sending_domain": {
3 "name": "mail.acme.example",
4 "tenant_id": 12
5 }
6 }
create-credential.json
1 {
2 "smtp_credential": {
3 "tenant_id": 12
4 }
5 }

Send with the platform token. Set reply_to to a plus-address so the next inbound message carries your conversation ID in thread_id.

send-agent-reply.js
1 export function createPostShibaSender({
2 apiKey,
3 teamId,
4 clusterId,
5 from,
6 inboxAddress,
7 tenant,
8 }) {
9 return async function sendReply({ message, conversation, text }) {
10 const [local, host] = inboxAddress.split("@");
11 const replyAddress = `${local}+${conversation.id}@${host}`;
12 const sourceMessageId = message.headers["message-id"];
13 const references = [
14 message.headers.references,
15 sourceMessageId,
16 ].filter(Boolean).join(" ");
17 const originalSubject = message.subject || "Your message";
18
19 const response = await fetch(
20 `https://postshiba.com/api/v1/teams/${teamId}/clusters/${clusterId}/sends`,
21 {
22 method: "POST",
23 headers: {
24 Authorization: `Bearer ${apiKey}`,
25 "Content-Type": "application/json",
26 },
27 body: JSON.stringify({
28 send: {
29 from,
30 to: [message.from],
31 reply_to: replyAddress,
32 subject: originalSubject.toLowerCase().startsWith("re:")
33 ? originalSubject
34 : `Re: ${originalSubject}`,
35 text,
36 headers: {
37 "In-Reply-To": sourceMessageId,
38 References: references,
39 },
40 unique_args: {
41 agent_id: conversation.agentId,
42 conversation_id: conversation.id,
43 },
44 tenant,
45 },
46 }),
47 },
48 );
49
50 const body = await response.json();
51 if (!response.ok || body.queued !== true) {
52 throw new Error(`PostShiba send failed: ${response.status} ${JSON.stringify(body)}`);
53 }
54
55 return body;
56 };
57 }

queued: true means at least one recipient was accepted by the injector. Send one recipient per request when the agent needs a clear delivery result for each conversation.

Use the delivery webhook to move the reply through processed, delivered, deferred, bounce, dropped, or spamreport in your UI. Match agent_id and conversation_id from unique_args.

6. Recover missed work by polling

PostShiba stores inbound mail for a configurable retention window. The default is 168 hours. Read retention_hours from the inbox and expires_at from each message. Polling is useful after downtime or when a queue publish fails.

PostShiba has no replay action for dead inbound deliveries. Poll before the message expires.

list-messages.sh
1 curl -sS \
2 --url "$CAPSULE_URL/api/v1/inboxes/3/inbound_messages" \
3 --header "Authorization: Bearer $CAPSULE_API_KEY"

The list returns at most 200 live messages, newest first. Fetching one message also returns its raw MIME and base64 attachment bytes.

get-message.sh
1 curl -sS \
2 --url "$CAPSULE_URL/api/v1/inboxes/3/inbound_messages/21" \
3 --header "Authorization: Bearer $CAPSULE_API_KEY"

Do not rely on PostShiba as long-term agent memory. Copy messages and attachment metadata into your own storage as they arrive.

Agent safety checklist

  • Keep the platform token on your server. Do not give it to the agent or browser.
  • Use lowercase, email-safe conversation IDs in plus-addresses.
  • Give each inbound message ID a unique database constraint.
  • Verify the raw body before JSON parsing.
  • Queue model work and return 2xx after the durable write.
  • Treat HTML, links, attachments, and quoted text as untrusted.
  • Keep tool permissions outside the email and outside the model's response.
  • Put a human in the loop for money movement, account changes, data deletion, and first contact with a new sender.
  • Record the prompt inputs, decision, tool calls, reply, PostShiba message_id, and delivery events.
  • Disable an agent's inbox with DELETE /api/v1/inboxes/:id when you retire it.

The API cannot change an inbox webhook after creation. Use the PostShiba dashboard to update its URL or format.

Previous

Build an email support desk on PostShiba

Next

Send basic transactional emails with PostShiba

About

PostShiba is the transactional email platform that powers Bento behind the scenes. You can build your own products, like Bento, on top of it.

© 2026 PostShiba by Backpack Internet Pty. Ltd. All rights reserved.

The same policies that govern Bento are applied to PostShiba → Privacy | Terms | Security