Inbound: A TypeScript SDK for Programmable Email Addresses and Webhooks

What Inbound Solves and Who It Targets

Inbound addresses a specific pain: wiring email into an application without assembling a chain of providers. The README sells it as a way to stop juggling email providers. The core idea is that you create a domain and an email address, and any incoming message triggers a webhook in your app. That removes the need to run an SMTP server, poll a mailbox, or build parsers for multipart content. The stated audience is agents and indie developers, people who want email as a feature, not a project. The SDK is TypeScript-first, which fits that audience. The examples show a Next.js route handler receiving webhooks, so it is aimed at modern JavaScript stacks. The service also covers sending, so you get both directions in one package. That is the whole pitch: one API key, one SDK, both send and receive.

The Mechanism: Email Addresses as Webhook Endpoints

The mechanism is straightforward from the README. You create a domain via inbound.domains.create, then create an email address with a webhookUrl. When someone sends mail to that address, Inbound parses the content and POSTs a payload to your webhook. The SDK exports a type guard, isInboundWebhookPayload, that you call in your route to validate the request before processing. The payload object contains an email property, which is what you log or act on. The README also mentions signature verification, but does not show how to verify it in code. That is a gap. The type guard checks the shape of the payload, but signature verification is a separate step. The README does not show the verification function or where the signature header comes from. You would need to inspect the OpenAPI spec or the source to get that detail. The flow is simple: send, parse, webhook. The parsing includes HTML and text extraction, and attachments go to S3 storage. You get a URL or reference to the attachment, presumably, though the README does not show the exact shape.

Getting It Running: Commands and Configuration

Installation is standard: npm install inboundemail or bun add inboundemail. The SDK requires an API key from inbound.new, which suggests a hosted service. The quick start shows four steps: initialize the client, add a domain, create an email address with a webhook URL, and then send a test email. The local development section is more concrete. You clone the repo, run bun install, then bun run dev to start a dev server. The key command is bun run inbound-webhook-test test@yourdomain.com, which the README claims lets you test email webhooks locally with no AWS needed. That is a notable claim because the production API uses S3 for attachments. The local test likely mocks or stubs the S3 dependency. The README does not explain what that command actually does, whether it starts a local SMTP listener or just simulates a webhook payload. You would have to run it to find out. The repo uses Bun, not npm, for development, which is a minor friction point if you are on Node with npm only.

API Features and What the README Promises

The README lists seven API features: REST API with OpenAPI spec, webhooks with signature verification, email parsing with HTML and text extraction, attachment handling with S3 storage, spam filtering and security checks, domain verification and DNS management, and usage tracking with billing integration. That is a broad surface. The OpenAPI spec is a real asset, because you can generate clients in other languages or inspect the exact endpoints. The spam filtering and security checks are mentioned but not detailed. No thresholds, no scoring, no configuration options. That is a limitation. You cannot tune the spam filter from the README. The usage tracking and billing integration suggest a metered pricing model, but no numbers are given. For an indie developer, the billing integration might be a concern, because it implies your email volume directly affects your bill. The README does not state free tier limits or overage costs.

Limitations and Failure Modes

The most obvious limitation is that Inbound is a hosted service with no self-hosting option. The README says to get an API key from inbound.new, and the local test command only tests webhooks, not the full service. If you need to run email infrastructure inside your own VPC for compliance reasons, this is the wrong tool. Another failure mode is webhook reliability. The README does not mention retry policies, dead letter queues, or delivery guarantees. If your webhook endpoint is down, you might lose emails. The signature verification is mentioned but not demonstrated, which is a risk because many webhook integrations get forged payloads. The README also does not say whether the webhook payload is signed with a secret you can rotate. The attachment handling relies on S3, which means you need to trust Inbound's AWS account or you need to fetch attachments from their S3 bucket. That could be a security or cost issue. The spam filtering is opaque, so you cannot whitelist or blacklist senders. That is a real constraint for a mail system.

Alternatives and How They Differ

The obvious alternative is to use a dedicated email API like SendGrid or Postmark for sending, and a separate service like Mailgun or a custom SMTP receiver for inbound. Those services have mature webhook systems, but they are separate products, so you still juggle providers, which is exactly what Inbound claims to eliminate. Another alternative is to run your own SMTP server with a library like Haraka or a framework like Nodemailer for sending, plus a parser like mailparser for inbound. That gives you full control but forces you to handle deliverability, DNS, and infrastructure. The difference is ownership: with Inbound you trade control for convenience. A more comparable alternative is a service like Cloudflare Email Routing, which forwards inbound email to a webhook or worker, but it does not send email, so you would still need a sending provider. Inbound combines both, which is its differentiator. The trade-off is that you depend on Inbound's uptime and pricing, whereas with a DIY stack you own every component.

Maintenance, Upgrade Cost, and License

The repository is MIT licensed, which is permissive. You can fork it and modify the SDK, but the SDK is just a client for a hosted API. The server-side code is not in this repo, or at least the README does not indicate that it is. The repo is the SDK and the dev server, not the whole service. That means the MIT license covers the client code, not the infrastructure that processes your emails. The maintenance cost is low for the SDK itself, because it is a thin wrapper over HTTP calls. The upgrade cost depends on the API versioning. The README does not mention versioning or breaking changes. The OpenAPI spec helps, because you can diff versions. The local test command is a useful tool for development, but it only tests webhook handling, not the full send and receive flow. You still need a real account to test sending. The repo has no recent releases listed, so the project may be early stage. That is a risk if you depend on it for production email. You should check the commit history and issue tracker before adopting.

Editorial conclusion

Adopt Inbound if you are an indie developer or agent builder who wants a single SDK for both sending and receiving email, with webhook delivery and parsing handled by a hosted service. Skip it if you need full control over email infrastructure or require a self-hosted option, because the README indicates a cloud API and an AWS-backed attachment pipeline. Before committing, verify the webhook signature verification mechanism, the exact pricing and rate limits, and whether the local test command truly avoids all AWS dependencies. Check the OpenAPI spec for the full API surface and confirm the service's uptime and data retention policies, since the repository offers no self-hosting instructions.

Official sources

1. Official documentation
2. Official README
3. Project repository