# inboxparse (Agent Skill)

> 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.

Page: https://timerise.ai/skills/inboxparse

Agent Skill `inboxparse`: https://github.com/timerise-ai/inboxparse. Category: AI & integrations. Runs on Next.js; backend: Postgres, Supabase or Firestore behind an `InboxStore` seam.

Latest release: v0.1.6 (2026-10-25).

Install: npx skills add timerise-ai/inboxparse. Timerise builds it on a brief; the price comes from the brief.

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.

Build an InboxParse email integration in a Next.js App Router app: a typed server-only client for the V1 API, a signed webhook receiver, a scheduled sync that stores every email whether or not a webhook arrived, and replies sent only after a person approves the exact text. Use when: (1) an app must receive, store, search or answer email from Gmail or IMAP mailboxes connected to InboxParse, (2) adding or auditing an InboxParse webhook endpoint, sync job or send and reply flow, (3) feeding email into an AI feature without letting the email's author steer it, (4) calling the InboxParse API directly for emails, threads, search, mailboxes, labels, contacts, webhooks or usage, (5) the user mentions: InboxParse, inboxparse.com, email API, email-to-LLM, parse emails, email webhook, X-InboxParse-Signature, whsec_, ip_ API key, INBOXPARSE_API_KEY, email.received, email.ai_processed, ai.suggested_response, /api/v1/emails, rate_limit_exceeded. Carries the facts the API reference leaves out, checked against the implementation: deliveries carry ids, never the email, are retried up to 5 times and disable the subscription after 10 failures; the signature covers the raw body with no timestamp; the list cursor pages on sent_at alone. Next.js App Router; the InboxStore interface is the seam, so Postgres, Supabase or Firestore holds the state. Not a mail server, not an email client UI, and not the InboxParse MCP server.

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 six 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, a stored email is shown without an API call, and one approved form sends one reply with the text the person submitted. This skill keeps its audit record in [CHANGELOG.md](CHANGELOG.md) rather than a `references/provenance.md`: each release says what it fixed, added or changed and how it was verified.

What it builds:
- A typed server-only V1 client
- A webhook receiver verifying X-InboxParse-Signature over the raw body
- A scheduled lookback sync that stores every email whether or not a webhook arrived
- Replies sent only after a person approves the exact text
- Email content never obeyed as instructions

When to use:
- 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](references/untrusted-content.md).

When not to use:
- Running a mail server, SMTP relay or deliverability setup: InboxParse sends through the mailbox's own SMTP.
- Giving an AI assistant direct access to a mailbox: use the InboxParse MCP server at `https://inboxparse.com/api/mcp`.
- Other email APIs (Gmail API, Microsoft Graph, SendGrid, Postmark): their own documentation.

Non-negotiables:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.

Not this:
- An AI assistant reading a mailbox for a person: The InboxParse MCP server, `https://inboxparse.com/api/mcp`
- Running a mail server, SMTP relay or deliverability setup: The mail provider's own tooling
- Gmail API, Microsoft Graph, SendGrid or Postmark integrations: That service's own documentation
- Notifying a team in Slack about new mail: [`slack-ai-bot`](https://github.com/timerise-ai/slack-ai-bot), fed from `onNewEmail`

Requirements:
- 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

What to tell your agent:
- 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.
- 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.
- Our InboxParse webhook endpoint keeps getting disabled and some emails never show up in the app. Find out why.

Agent eval results (newest per agent and prompt):
- Gemini CLI (gemini-3.8-flash) on v0.1.6, 2026-10-25: pass (In-memory store)
- Codex CLI (gpt-6.1-sol) on v0.1.6, 2026-10-25: pass (In-memory store)
- Claude Code (claude-opus-5-5) on v0.1.6, 2026-10-25: pass (In-memory store)

Recent releases:
- v0.1.6 (2026-10-25): Fix release, from scoring the prompt-1 agent eval runs of 0.1.5. Prose only; the templates were verified as for 0.1.1, with 21 tests and 16 without replies.
- v0.1.5 (2026-10-25): Fix release, from scoring the prompt-1 agent eval runs of 0.1.4. Prose only; the templates were verified as for 0.1.1, with 21 tests and 16 without replies.
- v0.1.4 (2026-10-25): Fix release, from scoring the prompt-1 agent eval runs of 0.1.3. Prose only; the templates were verified as for 0.1.1, with 21 tests and 16 without replies.
