Create a key to copy examples filled with your team.

Sending

SMTP, HTTP inject, and POST /sends.

SMTP and Kumo HTTP inject stay on the cluster host. POST /emails queues on the team's first sending-ready cluster so the first request does not need a cluster id. POST /sends still targets one cluster. MAIL FROM must be a verified domain. The cluster must be sending_ready. Set unique_args so X-Capsule-Unique-Args lands on the composed mail and comes back on delivery webhooks.

SMTP smtp.postshiba.com:587

AUTH PLAIN after STARTTLS on port 587.

username: Issued on the cluster. Shown as smtp_…
password: Shown once when you issue the credential
MAIL FROM: Must be a verified sending domain
X-Capsule-Unique-Args: JSON object. Comes back on every delivery webhook. Not added to the sent mail.

request.sh

1 swaks --server smtp.postshiba.com:587 --tls \

2 --auth PLAIN --auth-user smtp_9 --auth-password YOUR_PASSWORD \

3 --from hello@mail.example.com --to you@example.com \

4 --header "Subject: PostShiba test" \

5 --header 'X-Capsule-Unique-Args: {"campaign_id":"cmp_123","site":"docs"}' \

6 --body "hello from PostShiba"

response.json

1 {

2 "result": "250 2.0.0 Ok: queued"

3 }

POST https://inject.postshiba.com/api/inject/v1

Kumo HTTP inject. HTTP Basic is the SMTP username and password.

envelope_sender: Verified From domain
content: RFC822 string or {text_body, headers}
recipients: [{email}]
X-Capsule-Unique-Args: JSON object on content.headers. Stripped before send. Echoed on delivery webhooks.

request.sh

1 curl -sS -u 'smtp_9:YOUR_PASSWORD' \

2 -H 'Content-Type: application/json' \

3 -d '{"envelope_sender":"hello@mail.example.com","content":{"text_body":"hello from PostShiba","headers":{"From":"hello@mail.example.com","Subject":"PostShiba test","X-Capsule-Unique-Args":"{\"campaign_id\":\"cmp_123\",\"site\":\"docs\"}"}},"recipients":[{"email":"you@example.com"}]}' \

4 https://inject.postshiba.com/api/inject/v1

response.json

1 {

2 "success_count": 1,

3 "fail_count": 0,

4 "failed_recipients": [],

5 "errors": []

6 }

POST /api/v1/emails

Compose a message and queue it on the team's first sending-ready cluster. Same body as POST /sends. A flat body and {send:} both work. Returns 403 {error: cluster_not_ready, field: cluster} when none is ready.

from: Verified From address
to: Recipient list
unique_args: JSON object. Set as X-Capsule-Unique-Args on the composed mail.

request.sh

1 curl -sS -X POST \

2 -H 'Authorization: Bearer YOUR_API_KEY' \

3 -H 'Content-Type: application/json' \

4 -d '{"from":"hello@mail.example.com","to":["you@example.com"],"cc":[],"bcc":[],"reply_to":"hello@mail.example.com","subject":"PostShiba test","text":"hello from PostShiba","html":"\u003cp\u003ehello from PostShiba\u003c/p\u003e","attachments":[{"filename":"note.txt","content_type":"text/plain","content":"aGVsbG8="}],"headers":{"X-Campaign":"cmp_123"},"unique_args":{"campaign_id":"cmp_123","site":"docs"},"tenant":"default"}' \

5 https://postshiba.com/api/v1/emails

response.json

1 {

2 "queued": true,

3 "message_id": "abc@capsule.test",

4 "from": "hello@mail.example.com",

5 "to": [

6 "you@example.com"

7 ],

8 "subject": "PostShiba test",

9 "unique_args": {

10 "campaign_id": "cmp_123",

11 "site": "docs"

12 }

13 }

POST /api/v1/teams/:team_id/clusters/:cluster_id/sends

Compose a message and queue it on the cluster. sandbox true, "true", or 1 runs the same gates and compose, skips inject, and returns 200 {queued: false, message_id, from, to, subject, unique_args}. Optional Idempotency-Key replays the first 201 for 24 hours. A reused key with a different body is 409 idempotency_conflict. Failures return {error, field, message}. 422 is invalid. 403 is cluster_not_ready, domain_unverified, credential_missing, suppressed, or kyc_required.

from: Verified From address
to: Recipient list
unique_args: JSON object. Set as X-Capsule-Unique-Args on the composed mail.
sandbox: true, "true", or 1 composes without inject. Success is 200 with queued false. Any other value is a live send.
Idempotency-Key: Optional header, 1 to 256 characters. Same key and body returns the first 201 for 24 hours. Same key and a different body is 409.

request.sh

1 curl -sS -X POST \

2 -H 'Authorization: Bearer YOUR_API_KEY' \

3 -H 'Content-Type: application/json' \

5 https://postshiba.com/api/v1/teams/1/clusters/:cluster_id/sends

response.json

1 {

2 "queued": true,

3 "message_id": "abc@capsule.test",

4 "from": "hello@mail.example.com",

5 "to": [

6 "you@example.com"

7 ],

8 "subject": "PostShiba test",

9 "unique_args": {

10 "campaign_id": "cmp_123",

11 "site": "docs"

12 }

13 }

HEADER X-Capsule-Unique-Args

Tracking fields for delivery webhooks. We strip this header. The keys are flattened onto each SendGrid event and also appear as unique_args. X-SMTPAPI unique_args is accepted the same way.

campaign_id: Your campaign or broadcast id
category: transactional, newsletter, and the rest
account: Your team or account id
site: Your site or project id
tenant_id: On the webhook this stays the PostShiba tenant. Use account or site for your own id.

X-Capsule-Unique-Args.json

1 {

2 "campaign_id": "cmp_123",

3 "category": "transactional",

4 "account": "team_1",

5 "site": "docs"

6 }

response.json

1 {

2 "event": "delivered",

3 "email": "you@example.com",

4 "campaign_id": "cmp_123",

5 "category": "transactional",

6 "account": "team_1",

7 "site": "docs",

8 "unique_args": {

9 "campaign_id": "cmp_123",

10 "category": "transactional",

11 "account": "team_1",

12 "site": "docs"

13 }

14 }

Authentication

Clusters

Sending

SMTP smtp.postshiba.com:587

POST https://inject.postshiba.com/api/inject/v1

POST /api/v1/emails

POST /api/v1/teams/:team_id/clusters/:cluster_id/sends

HEADER X-Capsule-Unique-Args

About

Product

Company

Legal