PostShiba SDKs

Note

PostShiba skills connect agents to MCP for first send, domains, inboxes, and sandbox mail.

HTTP clients and mail adapters for the PostShiba API.

This repo is the write target. Language repos under postshiba are one-way mirrors. JavaScript packages are on npm under @postshiba. Other languages install from GitHub.

script/split-push

Creates missing repos when CREATE_REPOS=1 and gh can write to the postshiba org. Force-pushes each packages/<lang> to postshiba/postshiba-<lang>.

Libraries

• Skills (source) Cursor plugin. MCP plus agent skills.
• CLI (source) Terminal app. Interactive prompts for humans, JSON for scripts.
• Node.js (source, NestJS included)
• Convex (source) component. Durable send plus webhooks.
• Inngest (source) adapter. Send inside step.run.
• Trigger.dev (source) adapter. Send inside a task.
• Python (source, Django included)
• PHP (source, Laravel and Symfony included)
• Ruby (source, ActionMailer included)
• Go (source)
• Java (source)
• Rust (source)
• .NET (source)
• Elixir (source, Swoosh included)
• Dart (source)
• WordPress (source) plugin. Not a language client.

How It Works

Each package is a thin HTTPS client. Authenticate with a platform application token. Send through POST /api/v1/emails. Manage clusters, domains, inboxes, and the rest of the catalog from the same client.

The Convex package is a component. It enqueues mail from a mutation and delivers through POST /api/v1/teams/:teamId/clusters/:clusterId/sends.

The Inngest and Trigger.dev packages wrap that same cluster send. Inngest uses step.run. Trigger.dev uses a task. A 429 with error throttled waits until the next hour. Permanent errors do not retry.

Failed REST calls raise a typed error with error, field, and message. A 429 with error throttled is the cluster hourly send limit. Do not retry that send immediately. Wait until the next hour. Each language README has the catch shape.

Mail adapters live in the language package. They call emails.send. The core client loads without Rails, Laravel, Django, Nest, or Swoosh. The WordPress plugin replaces wp_mail and lives in its own package.

Publishing

JavaScript packages publish to npm under @postshiba, plus the postshiba alias for the Node client.

script/npm-check
script/npm-publish
script/npm-publish --publish

script/npm-check builds each package, packs it, and imports the tarball from a fresh Node project. script/npm-publish runs that check, then prints what it would publish. Pass --publish only from a clean main after npm whoami. Already-published versions are skipped.

Testing

script/test

Each package also has its own test command in its README. Tests mock HTTP. They do not call production.

Java tests need a JDK 17 or later. Dart tests need the Dart SDK. script/test fails if those are missing from PATH.

Contributing

See CONTRACT.md for the shared resource map and fixture rules.