@inbin/core

@inbin/core

Official SDK for Inbin — email in, JSON out. Typed client for the REST API plus webhook signature verification. Zero dependencies, Node 18+.

Install

npm i @inbin/core

Quickstart

import { Inbin } from "@inbin/core";

const inbin = new Inbin({ apiKey: process.env.INBIN_API_KEY! });

// 1. Create an inbox — a permanent forwarding address
const inbox = await inbin.inboxes.create({ name: "going-deals" });
console.log(inbox.address); // [e-mail]

// 2. Declare what to extract from every email
await inbin.schemas.put({
  extract: {
    deals: {
      type: "array",
      items: {
        destination_city: { type: "string", required: true },
        price_usd: { type: "number", required: true },
      },
    },
  },
  hallucination_guard: true,
});

// 3. Point Inbin at your webhook
await inbin.apps.update({ webhook_url: "https://your.app/webhooks/inbin" });

Verify webhooks

Always verify the HMAC before trusting a delivery. Pass the raw request body — the signature covers the exact bytes Inbin sent.

import { verifyWebhook } from "@inbin/core";

// Next.js route handler
export async function POST(request: Request) {
  const raw = await request.text();
  const event = verifyWebhook(raw, request.headers, process.env.INBIN_WEBHOOK_SECRET!);
  // event.extracted is your schema-shaped JSON
  return new Response("ok");
}

// Express
app.post("/webhooks/inbin", express.raw({ type: "*/*" }), (req, res) => {
  const event = verifyWebhook(req.body, req.headers, process.env.INBIN_WEBHOOK_SECRET!);
  res.sendStatus(200);
});

Throws InbinError (code: "bad_signature") on any mismatch.

API surface

Method	Endpoint
inbin.inboxes.create({ name? })	POST /v1/inboxes
inbin.inboxes.list()	GET /v1/inboxes
inbin.inboxes.get(id)	GET /v1/inboxes/:id
inbin.inboxes.rename(id, name)	PATCH /v1/inboxes/:id
inbin.inboxes.delete(id)	DELETE /v1/inboxes/:id
inbin.schemas.put({ extract, hallucination_guard? })	PUT /v1/schemas
inbin.schemas.current()	GET /v1/schemas/current
inbin.events.list(params?)	GET /v1/events
inbin.events.get(id)	GET /v1/events/:id
inbin.events.redeliver(id)	POST /v1/events/:id/redeliver
inbin.query(q)	POST /v1/query
inbin.apps.me()	GET /v1/apps
inbin.apps.update({ name?, webhook_url? })	PATCH /v1/apps

All methods throw InbinError with .status and .code on failure.

Query

Your inbox as a table. Filter, sort, project, flatten array records, group and aggregate over everything your schemas extracted. One request, no database on your side.

const { rows } = await inbin.query({
  flatten: "deals",
  where: [{ field: "price_usd", op: "lt", value: 300 }],
  group_by: "destination_city",
  aggregate: [{ fn: "avg", field: "price_usd", as: "avg_price" }],
});
// [{ destination_city: "Lisbon", avg_price: 274.5 }, ...]

Ops: eq, neq, gt, gte, lt, lte, contains, in, exists. Aggregates: count, sum, avg, min, max. Limit caps at 200.

MCP

Every Inbin application is also an MCP server — see @inbin/mcp to connect Claude Desktop, Cursor, or any MCP client to your parsed events.

License

MIT.