Create a key to copy examples filled with your team.

Create an account Sign in

Build an ESP on PostShiba

Give each customer their own domains, credentials, sending data, and controls.

PostShiba is a good fit when your product sends on behalf of other businesses. You keep the customer-facing API and dashboard. PostShiba handles domain verification, SMTP credentials, message injection, delivery events, bounces, and suppressions.

Within a PostShiba team, use a tenant to group each customer's domains, SMTP credentials, inboxes, and suppressions.

A sensible account model

Use this mapping:

Your product PostShiba
Your company One PostShiba team
Sending environment One shared-IP cluster
Customer or workspace One tenant
Customer sending domain A domain owned by that tenant
Customer SMTP login A credential owned by that tenant
Delivery stream Team webhook, routed by tenant slug
Do-not-send list Tenant suppressions

Start with one cluster unless you have a real operational reason to separate traffic. Customer-created clusters use the shared IP pool. A tenant already gives you the isolation most ESP products need.

Your platform application token can access the whole PostShiba team. Never put it in customer code or a browser. If customers need direct SMTP, give each one a tenant-scoped SMTP credential instead.

1. Prepare the team

Finish PostShiba's sender review, then create a cluster. You only do this once for the sending environment.

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": "customer-mail",
13 "size": "small",
14 "region": "manual"
15 }
16 }'

Save the returned cluster ID and endpoints. Do not accept production sends until sending_ready is true.

The shell examples share these variables. Run the exports in your current shell, or move them to setup.sh and load it with source setup.sh.

Create one delivery webhook for the team:

create-webhook.sh
1 curl -sS \
2 --request POST \
3 --url "$CAPSULE_URL/api/v1/teams/$TEAM_ID/webhook_endpoints" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY" \
5 --header "Content-Type: application/json" \
6 --data '{
7 "webhook_endpoint": {
8 "url": "https://esp.example.com/webhooks/capsule",
9 "event_types": [
10 "processed",
11 "delivered",
12 "deferred",
13 "bounce",
14 "dropped",
15 "spamreport"
16 ]
17 }
18 }'

Store the returned signing secret. PostShiba sends a JSON array in the SendGrid Event Webhook shape. Authenticated sends normally include the PostShiba tenant slug as tenant_id. Keep your own routing ID in unique_args and alert when an event unexpectedly has no tenant.

2. Provision a customer

Provisioning has three API calls:

  1. Create a tenant.
  2. Create a sending domain under that tenant.
  3. Create an SMTP credential under that tenant.

This small client keeps the sequence in one place:

postshiba-client.js
1 export class PostShibaClient {
2 constructor({ baseUrl, apiKey, teamId, clusterId }) {
3 this.baseUrl = baseUrl;
4 this.apiKey = apiKey;
5 this.teamId = teamId;
6 this.clusterId = clusterId;
7 }
8
9 async request(path, { method = "GET", body } = {}) {
10 const response = await fetch(`${this.baseUrl}${path}`, {
11 method,
12 headers: {
13 Authorization: `Bearer ${this.apiKey}`,
14 ...(body ? { "Content-Type": "application/json" } : {}),
15 },
16 body: body ? JSON.stringify(body) : undefined,
17 });
18
19 if (!response.ok) {
20 throw new Error(`PostShiba ${method} ${path}: ${response.status} ${await response.text()}`);
21 }
22
23 if (response.status === 204) return null;
24 return response.json();
25 }
26
27 async provisionCustomer({ name, slug, domain }) {
28 const tenant = await this.request(
29 `/api/v1/teams/${this.teamId}/tenants`,
30 {
31 method: "POST",
32 body: { tenant: { name, slug } },
33 },
34 );
35
36 const sendingDomain = await this.request(
37 `/api/v1/teams/${this.teamId}/sending_domains`,
38 {
39 method: "POST",
40 body: {
41 sending_domain: {
42 name: domain,
43 tenant_id: tenant.id,
44 },
45 },
46 },
47 );
48
49 const smtpCredential = await this.request(
50 `/api/v1/teams/${this.teamId}/clusters/${this.clusterId}/smtp_credentials`,
51 {
52 method: "POST",
53 body: {
54 smtp_credential: {
55 tenant_id: tenant.id,
56 },
57 },
58 },
59 );
60
61 return { tenant, sendingDomain, smtpCredential };
62 }
63 }

Call it from your onboarding job:

provision-customer.js
1 import { PostShibaClient } from "./postshiba-client.js";
2
3 const capsule = new PostShibaClient({
4 baseUrl: "https://postshiba.com",
5 apiKey: process.env.CAPSULE_API_KEY,
6 teamId: 1,
7 clusterId: 4,
8 });
9
10 const setup = await capsule.provisionCustomer({
11 name: "Acme Florist",
12 slug: "acme-florist",
13 domain: "mail.acme.example",
14 });
15
16 console.log({
17 capsuleTenantId: setup.tenant.id,
18 capsuleTenantSlug: setup.tenant.slug,
19 capsuleDomainId: setup.sendingDomain.id,
20 dkimHost: setup.sendingDomain.dkim_cname_host,
21 dkimValue: setup.sendingDomain.dkim_cname_target,
22 returnPathHost: setup.sendingDomain.return_path_host,
23 returnPathValue: setup.sendingDomain.return_path_target,
24 optionalSpf: setup.sendingDomain.spf_record,
25 smtpUsername: setup.smtpCredential.username,
26 });

The REST API returns the SMTP password on credential creation. Do not write it to application logs. If your product offers SMTP, move it straight into encrypted secret storage until the customer retrieves it. Authorized PostShiba dashboard users can currently reveal the encrypted password again. If all mail goes through your own REST API, your application does not need to keep a copy. PostShiba keeps the credential it needs for injection.

Use explicit customer slugs. They appear in webhooks and make support work much easier than a generated numeric ID alone.

3. Guide the customer through DNS

Show the three DNS values from the domain response in your own dashboard:

Record Required Purpose
DKIM CNAME Yes Signs mail for the customer's domain
Return-path CNAME Yes Routes bounces back to PostShiba
SPF TXT include No Optional SPF record shown by PostShiba

Do not invent or transform these values. DNS dashboards vary in how they display the host, so give the customer a copy button for both the host and target.

When the customer says the records are ready, ask PostShiba to check them:

verify-domain.sh
1 curl -sS \
2 --request POST \
3 --url "$CAPSULE_URL/api/v1/sending_domains/8/verify" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY"

Read the domain until the required states are verified:

get-domain.sh
1 curl -sS \
2 --url "$CAPSULE_URL/api/v1/sending_domains/8" \
3 --header "Authorization: Bearer $CAPSULE_API_KEY"

Only mark the domain ready in your product when both dkim_status and return_path_status are verified. SPF is reported separately and does not block sending.

PostShiba allows mail from any address at the verified domain. Your product can add its own sender-name or local-part policy if the customer should only use approved addresses.

4. Send for the customer

Your API should authenticate the customer, look up the PostShiba tenant on your server, and call PostShiba with your platform token.

Pass the tenant slug on every send. When the slug resolves, PostShiba scopes domain lookup, credential lookup, and suppressions to that customer.

Only pass slugs from your server-side customer mapping. The current send endpoint does not reject an unknown tenant value. An unknown value falls back to team-wide domain and credential lookup plus the default tenant's suppressions. Treat a missing mapping as a hard failure before you call PostShiba.

send-for-customer.js
1 export async function sendForCustomer({
2 apiKey,
3 teamId,
4 clusterId,
5 customer,
6 message,
7 }) {
8 if (!customer.capsuleTenantSlug) {
9 throw new Error("Customer has no PostShiba tenant mapping");
10 }
11
12 const response = await fetch(
13 `https://postshiba.com/api/v1/teams/${teamId}/clusters/${clusterId}/sends`,
14 {
15 method: "POST",
16 headers: {
17 Authorization: `Bearer ${apiKey}`,
18 "Content-Type": "application/json",
19 },
20 body: JSON.stringify({
21 send: {
22 from: message.from,
23 to: message.to,
24 cc: message.cc || [],
25 bcc: message.bcc || [],
26 reply_to: message.replyTo,
27 subject: message.subject,
28 text: message.text,
29 html: message.html,
30 attachments: message.attachments || [],
31 headers: message.headers || {},
32 unique_args: {
33 customer_id: customer.id,
34 transmission_id: message.id,
35 category: message.category,
36 },
37 tenant: customer.capsuleTenantSlug,
38 },
39 }),
40 },
41 );
42
43 const body = await response.json();
44 if (!response.ok || body.queued !== true) {
45 throw new Error(`PostShiba send failed: ${response.status} ${JSON.stringify(body)}`);
46 }
47
48 return body;
49 }

Store your transmission_id with PostShiba's returned message_id. Check queued, not only HTTP 201. queued: true means at least one recipient was accepted by the injector. It does not guarantee that every recipient queued because the REST response omits partial rejection details. Send one recipient per request when you need per-recipient certainty. Delivery is a later event.

One send request queues one message. PostShiba does not provide batch sending, scheduling, hosted templates, or an idempotency key on this endpoint. Your product should own those features if customers need them.

If customers connect over SMTP instead, give them the cluster's smtp_endpoint, the tenant credential, port 587, STARTTLS, and AUTH PLAIN. PostShiba does not support AUTH LOGIN. SMTP AUTH validates the credential and tenant state. PostShiba then validates the envelope MAIL FROM against that tenant's verified domains when it accepts the message.

5. Route delivery events

Verify the exact webhook body before parsing it. Then route each event by tenant_id and your transmission_id.

delivery-webhook.js
1 import { createHmac, timingSafeEqual } from "node:crypto";
2
3 function verify({ body, 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}.${body}`)
11 .digest();
12 const received = Buffer.from(signature.slice(7), "hex");
13
14 return expected.length === received.length &&
15 timingSafeEqual(expected, received);
16 }
17
18 export function createDeliveryHandler({ secret, updateTransmission }) {
19 return async function handle(request) {
20 const body = await request.text();
21 const timestamp = request.headers.get("X-Capsule-Timestamp");
22 const signature = request.headers.get("X-Capsule-Signature");
23
24 if (!verify({ body, timestamp, signature, secret })) {
25 return new Response("invalid signature", { status: 401 });
26 }
27
28 const events = JSON.parse(body);
29 for (const event of events) {
30 await updateTransmission({
31 tenantSlug: event.tenant_id,
32 transmissionId: event.transmission_id,
33 eventId: event.sg_event_id,
34 type: event.event,
35 recipient: event.email,
36 occurredAt: new Date(event.timestamp * 1000),
37 response: event.response,
38 reason: event.reason,
39 });
40 }
41
42 return new Response(null, { status: 204 });
43 };
44 }

Add a unique constraint on sg_event_id so retries do not apply an event twice. Store first, return 2xx, then run slower customer notifications in a queue.

PostShiba retries failed deliveries and marks them dead after six failed attempts. Replay dead deliveries from the PostShiba dashboard. Replay is not exposed by the API.

6. Make suppressions part of your product

PostShiba creates a tenant suppression after a hard bounce or spam report. A later send to that address returns 403 {"error":"suppressed"}.

List the customer's suppressions with the team endpoint and filter the returned rows by tenant_id in your application:

list-suppressions.sh
1 curl -sS \
2 --url "$CAPSULE_URL/api/v1/teams/$TEAM_ID/suppressions" \
3 --header "Authorization: Bearer $CAPSULE_API_KEY"

Add an address when your customer asks you not to send:

add-suppression.sh
1 curl -sS \
2 --request POST \
3 --url "$CAPSULE_URL/api/v1/teams/$TEAM_ID/suppressions" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY" \
5 --header "Content-Type: application/json" \
6 --data '{
7 "suppression": {
8 "email": "do-not-send@example.net",
9 "tenant_id": 12
10 }
11 }'

Manual suppressions get the reason manual. The other reasons are bounce and spamreport.

Removing a suppression is a deliberate customer action:

remove-suppression.sh
1 curl -sS \
2 --request DELETE \
3 --url "$CAPSULE_URL/api/v1/suppressions/7" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY"

7. Add inbound mail when your product needs it

An ESP does not have to stop at outbound mail. Create an inbox under the customer's tenant when you want to offer replies, support addresses, or agent mailboxes.

This example binds an inbox to the customer's verified sending domain:

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 replies",
9 "local_part": "reply",
10 "sending_domain_id": 8,
11 "tenant_id": 12,
12 "webhook_url": "https://esp.example.com/webhooks/capsule/inbound",
13 "webhook_format": "json"
14 }
15 }'

Publish the returned MX record on inbound.{sending_domain}, then call POST /api/v1/inboxes/:id/verify. Do not move the sending domain's own MX record to PostShiba.

PostShiba can also issue a hosted address without DNS. Omit sending_domain_id and local_part, and PostShiba generates an address on its inbound zone.

Each inbox has its own signing secret. The inbound webhook is a JSON object, while outbound delivery webhooks are JSON arrays. Store incoming mail in your own database. Retention defaults to 168 hours, but it is configurable. Read retention_hours and each message's expires_at instead of assuming the default.

The support desk guide shows threading and replies. The AI agent inbox guide adds queueing and safety controls.

8. Pause a customer cleanly

Tenant suspension is the fastest kill switch. It stops that tenant's sending credentials, domains, and inboxes without affecting other customers. New inbound mail will be rejected until the tenant resumes.

suspend-tenant.sh
1 curl -sS \
2 --request POST \
3 --url "$CAPSULE_URL/api/v1/tenants/12/suspend" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY"

Resume after you resolve the problem:

resume-tenant.sh
1 curl -sS \
2 --request POST \
3 --url "$CAPSULE_URL/api/v1/tenants/12/resume" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY"

Disable a leaked or retired SMTP credential separately:

disable-credential.sh
1 curl -sS \
2 --request DELETE \
3 --url "$CAPSULE_URL/api/v1/teams/$TEAM_ID/clusters/4/smtp_credentials/9" \
4 --header "Authorization: Bearer $CAPSULE_API_KEY"

Deleting a tenant is intentionally strict. PostShiba rejects deletion while it owns any sending domain, SMTP credential, or inbox. Disabled credentials and inboxes still count, and the API does not hard-delete them. The public API also cannot delete sending domains or update and delete webhook endpoints. The current dashboard does not expose every cleanup control, so plan for operator-assisted cleanup.

Before you onboard customers

  • Keep a durable mapping between your customer ID and PostShiba tenant ID and slug.
  • Serialize provisioning per customer. Repeating create calls can make duplicate resources or hit uniqueness validation.
  • Keep the platform application token in one server-side integration service.
  • Encrypt SMTP passwords and reveal them once.
  • Gate customer sending on your own status plus PostShiba's domain and cluster status.
  • Use unique_args for non-secret routing IDs. Values appear on delivery webhooks.
  • Deduplicate delivery events on sg_event_id.
  • Expose suppressions and suspension in your own customer support tools.
  • Keep a local audit trail for resource creation, credential issue, suspension, and deletion.

Previous

Sending emails

Next

Build an email support desk on 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