Clickable prototype in 48h
AI & integrations

InboxParse email

An InboxParse email integration in a Next.js app: a typed server-only client, a webhook receiver that verifies every delivery, a scheduled sync that stores every email whether or not a webhook arrived, and replies sent only after a person approves the exact text.

Repository
timerise-ai/inboxparse
Released
October 8, 2026
Build it with TimeriseBuild it yourself
npx skills add timerise-ai/inboxparse
v0.1.0
Current release
9
Reference docs
6
Non-negotiables
MIT
License

The problem

What problem does InboxParse email solve?

A booking system lives next to an inbox. Customers write to ask, to reschedule, to complain, and the answers sit in a mailbox that the system cannot see. Bringing that email into the app, so it can be stored, searched, summarised and answered from the customer's own record, is what InboxParse is for.

The webhook is the part that looks finished first, and it is the part that cannot be trusted. A delivery carries only an email id, and it can arrive late, twice, out of order, replayed by someone else, or not at all. An integration built on webhooks alone loses email quietly. And every field of an email, its AI summary and suggested reply included, was written by someone outside the app, so an assistant that acts on it acts for a stranger.

This skill gives a coding agent the integration the way we build it: a webhook receiver that verifies the signature over the raw body, fetches the email with its own key and answers at once; a scheduled sync that walks the mailbox and stores whatever is missing, resuming where it stopped; and a reply flow in which a person approves the exact text before anything is sent.

The module

What does the skill build?

An agent with this skill builds one module for a Next.js App Router app, on your stack. For InboxParse email that module consists of:

  • 1. A typed server-only V1 client
  • 2. A webhook receiver verifying X-InboxParse-Signature over the raw body
  • 3. A scheduled lookback sync that stores every email whether or not a webhook arrived
  • 4. Replies sent only after a person approves the exact text
  • 5. Email content never obeyed as instructions

What it needs from you

  • A Next.js App Router app with TypeScript, reachable from the internet for webhooks, with a scheduler such as Vercel Cron for the sync
  • An InboxParse workspace with a connected mailbox, a member key in INBOXPARSE_API_KEY and, to reply, an admin key in INBOXPARSE_ADMIN_API_KEY
  • INBOXPARSE_WEBHOOK_SECRET and CRON_SECRET, both documented in references/client.md
  • A durable store for the InboxStore seam

Provenance

Where do the rules come from?

This skill is written by the engineer who has shipped this integration, an email intake and reply module in a Next.js app, starting from the InboxParse V1 specification and checked against the API's implementation for the details the specification leaves out. The templates hold five properties, each verified by the suite in references/testing.md: a delivery is accepted only with a valid signature over its raw body, each email is fetched once however many deliveries name it, every email in the sync window is stored including those that share a page's boundary timestamp, a capped sync resumes where it stopped, and one approved form sends one reply with the text the person submitted. This skill keeps its audit record in CHANGELOG.md rather than a references/provenance.md: each release says what it fixed, added or changed and how it was verified.

Each entry is a rule that changed because the integration taught something the specification did not.

  1. Release 0.1.0, 2026-10-08

    First release under the Timerise Skills standard. The skill now builds an InboxParse integration in a Next.js App Router app: a typed client, a signed webhook receiver, a scheduled sync and an approved reply flow, with a 17-test suite. It replaces an earlier version of this skill that documented the V1 API for an agent calling it directly. Every API fact below was checked against the InboxParse V1 implementation and its reference documentation on 2026-10-08, and the templates were verified by copying them into the index's eval fixture, a fresh Next.js 16 App Router app with strict and noUncheckedIndexedAccess, where npm run typecheck, npm run build and npm test (17 tests) pass with no InboxParse variable set.

    • The webhook signature is documented as it is sent: X-InboxParse-Signature: sha256=<hex>, HMAC-SHA256 over the exact body. The earlier version named hmac as an auth_type; the values are none, bearer, basic and header, and they add transport auth on top of the signature
    • Webhook payloads are documented as ids only, with camelCase keys: email.received carries messageId, threadId, direction, hasAttachments and an optional length; email.ai_processed carries messageId, labelId, labelName. The earlier version said they carried the full email
    • Delivery behaviour is stated: one attempt with a 10-second timeout, retries up to 5 attempts, the subscription disabled after 10 failures in a row, and is_active: true resetting it. The secret is generated as whsec_... when omitted and returned once
    • GET /emails and POST /search default to limit 50, not 20, and their items carry no content; format applies only to GET /emails/:id and GET /threads/:id. Email ids are UUIDs, not msg_ prefixed
    • reply_to on POST /emails/send is one address, not an array. POST /labels requires color as six-digit hex. POST /webhooks/:id/test takes a member key
    Show 2 more
    • The error table adds invalid_key, missing_query, missing_workspace_id, smtp_error (502) and insert_error, and states that 429 is a monthly quota with no Retry-After
    • The example scripts build JSON with jq --arg instead of interpolating arguments into a JSON string, which broke on a quote in a subject and let an argument add fields; they pass the key to curl from a process substitution so it does not appear in the process list
Read the full record in CHANGELOG.md

Non-negotiables

What are the 6 rules the module never breaks?

Every module built from this skill holds these, whoever builds it. The same list is in the skill's README and SKILL.md, so the agent reads it before it writes a line.

  1. Verify the signature over the raw body before parsing it.

    InboxParse signs the exact bytes with HMAC-SHA256, and any re-serialisation changes them; the check is constant-time and length-checked, and signature.test.ts holds that a whitespace change, another secret or a truncated digest fails.

  2. A webhook is a hint; the API is the record.

    A delivery has ids only, a 10-second timeout and up to 5 attempts, and 10 failures disable the subscription, so the receiver answers at once and the sync stores what any delivery missed. ingest.test.ts holds that the sync stores every email in its window, including those at a page's boundary timestamp, and resumes a capped walk.

  3. Ingest is keyed by the email id.

    Retries, replays, email.ai_processed and overlapping sync windows all name the same id; one detail fetch per new id and onNewEmail once is what ingest.test.ts and webhook.test.ts verify.

  4. Email content is untrusted data.

    Its author is outside the app and the ai.* fields are generated from it, so it is rendered as text, never as HTML, never interpolated into code and never obeyed by a model; the email page renders it through React's escaping and marks the generated fields as generated.

  5. Nothing is sent without a person approving the exact text.

    ai.suggested_response only prefills the form, and a claimed draft makes one form send at most once; drafts.test.ts holds that two concurrent approvals send one reply with the submitted text.

  6. Keys stay on the server, and each path holds the least it needs.

    Reads use a member key, which InboxParse refuses on every write; only the approval path reads the admin key; no key or body is logged. ingest.test.ts and drafts.test.ts check which key each call carries.

Fit

When should you use it, and when not?

Use it for

  • Building or auditing an app that receives, stores, searches or replies to email through InboxParse.
  • Adding an InboxParse webhook, a sync job, an AI feature over email, or a reviewed reply flow.
  • Calling the V1 API directly from scripts: see assets/examples/ and the rules in untrusted-content.md.

Not for

  • An AI assistant reading a mailbox for a personInsteadThe InboxParse MCP server, https://inboxparse.com/api/mcp
  • Running a mail server, SMTP relay or deliverability setupInsteadThe mail provider's own tooling
  • Gmail API, Microsoft Graph, SendGrid or Postmark integrationsInsteadThat service's own documentation
  • Notifying a team in Slack about new mailInstead`slack-ai-bot`, fed from onNewEmail

Build it yourself

How do I install it?

One command. The skills.sh CLI installs the skill into every skills-compatible agent it finds.

$ npx skills add timerise-ai/inboxparse

Claude Code

Invoke with /inboxparse

Codex CLI

Invoke with $inboxparse

Gemini CLI

Invoke with /skills

Name the agents instead with -a, for example npx skills add timerise-ai/inboxparse -a claude-code -a codex. Or clone the repository into your agent's skills folder. Nothing in it is agent-specific.

What is inside the repository (21 entries)
  • SKILL.mdEntry point: when to use and when not to, the architecture, eight critical facts, six hard rules, the quick start and the reference directory
  • README.mdThis file: the human-facing front door
  • CHANGELOG.mdEvery release, newest first, and the record of what each one fixed, added or changed and how it was verified, which is this skill's provenance
  • CLAUDE.mdWhat this repository is and its editing conventions, for an agent editing the skill itself
  • LICENSEMIT
  • references/client.mdEnvironment variables and key roles, the V1 response types, the server-only client and its calls
  • references/webhooks.mdWhat a delivery carries and how it is retried, registering the subscription, the signature check and the receiver route
  • references/sync.mdThe lookback window, the boundary-timestamp query, the resumable walk, the cron route and its cost in API calls
  • references/replies.mdReplies a person approves: the claimed draft, the server action, the form and the email page
  • references/untrusted-content.mdThe rules for email content and AI fields in the app and for an agent using the API directly
  • references/adaptation.mdThe InboxStore seam with its Postgres statements, the integration points, the rename table, the order of work and the non-negotiables
  • references/testing.mdThe Vitest setup, the fake V1 API and the 17-test suite carried into the app
  • references/api-reference.mdEvery V1 endpoint: parameters, response shapes, contacts, webhooks, usage and the MCP server
  • references/error-codes.mdEvery V1 error code with its HTTP status and what the app does about it
  • assets/examples/list-emails.shList the newest emails
  • assets/examples/get-email.shFetch one email with its markdown body
  • assets/examples/search-emails.shHybrid search
  • assets/examples/send-email.shSend a new email, after the user has confirmed it
  • assets/examples/setup-webhook.shCreate the subscription and write its one-time secret to a private file
  • evals/The prompts an operator types after installing (prompts.md) and one file per agent eval: the skill installed into an empty Next.js app, one prompt, no help, then type-checked, built and tested
  • .github/workflows/agent-eval.ymlRuns the agent evals on every published release through the index's reusable workflow; the same in every skill

Recent releases

  1. v0.1.0October 8, 2026

    First release under the Timerise Skills standard. The skill now builds an InboxParse integration in a Next.js App Router app: a typed client, a signed webhook receiver, a scheduled sync and an approved reply flow, with a 17-test suite. It replaces an earlier version of this skill that documented the V1 API for an agent calling it directly. Every API fact below was checked against the InboxParse V1 implementation and its reference documentation on 2026-10-08, and the templates were verified by copying them into the index's eval fixture, a fresh Next.js 16 App Router app with strict and noUncheckedIndexedAccess, where npm run typecheck, npm run build and npm test (17 tests) pass with no InboxParse variable set.

SKILL.md README.md CHANGELOG.md

After installing

What do I tell my agent?

Say what you need in your own words; the skill supplies the how. These are starting points, and the ones we tested say how it went.

  1. Our support inbox is connected to InboxParse. Store every email it receives in this app, as soon as InboxParse tells us about it, without missing any if a notification never arrives, and show each one on its own page.

    In-memory storeClaude CodeBuilt, checks pass

  2. On each email page, let a signed-in teammate edit InboxParse's suggested reply and send it from our mailbox. A reply must never go out unless someone pressed send.

    In-memory store

  3. Our InboxParse webhook endpoint keeps getting disabled and some emails never show up in the app. Find out why.

Tested

How does it do in each agent?

We install the skill into an empty Next.js app, give the agent one of the prompts above and no further help, then type-check, build and run the tests it left behind. Nothing is fixed by hand before the checks, and a failing run is published like a passing one. The procedure and every result are public, and the first prompt runs again before each release.

  • Claude Code2.1.293

    claude-opus-5-5

    Built, checks pass
    Our support inbox is connected to InboxParse. Store every email it receives in this app, as soon as InboxParse tells us about it, without missing any if a notification never arrives, and show each one on its own page.
    Typecheck: passBuild: passTests: pass
    Time
    3 min
    Changed
    26 files, +2,113 lines
    Stack
    In-memory store
    Skill
    v0.1.0
    Run
    Oct 8, 2026

    Result fileAgent log

Not run yet in Codex CLI or Gemini CLI.

Build it with Timerise

How long does it take, and what does it cost?

We quote this module per project. The price depends on what it has to connect to. The path to a number is short and free:

  1. Step 1

    Brief

    Tell us what the module must connect to. Takes minutes, in a chat.

  2. Step 2

    Prototype in 48 hours

    A clickable prototype of your system and a quote, at no cost.

  3. Step 3

    Build and handoff

    One project price. Source code, documentation and IP are yours.

Two ways to get InboxParse email

Build it yourself

Install the skill. Your own agent builds the module.

  • MIT licensed, no strings
  • Runs in Claude Code, Codex CLI and Gemini CLI
  • The same rules our engineers build by
$ npx skills add timerise-ai/inboxparse
Install the skill

Build it with Timerise

Send a brief. We build InboxParse email into a system you own.

  • Clickable prototype and a quote within 48 hours, free
  • One project price, no subscription, no commission
  • Source code, documentation and IP handed over
3 years of support included.
Start the brief

Generated from the skill's own files at commit a8f4689. Every rule above links to where the repository says it. All skills