Email Parsing API: Inbound Mail as Structured JSON, Zero MIME Handling

From raw MIME to typed JSON in one hop

The typical path to parsed inbound email: configure MX records, set up an IMAP client, handle OAuth token refresh, fetch raw messages, load a MIME parser, strip HTML, decode quoted-printable, reconstruct threads from In-Reply-To headers. Mails.ai collapses that into a single webhook call:

// What your endpoint receives — no parsing needed on your side
{
  "event": "message.received",
  "message_id": "msg_01jx8kpq2mfr4v",
  "thread_id": "thr_01jx4nbq8cde7w",
  "from": { "address": "alice@example.com", "name": "Alice" },
  "to": [{ "address": "support@yourworkspace.mails.ai" }],
  "subject": "Re: Order #2241",
  "body_text": "Hi — still waiting on the tracking number for my order.",
  "body_html": "<p>Hi — still waiting on the tracking number for my order.</p>",
  "injection_score": 0.02,
  "attachments": [],
  "received_at": "2026-09-06T08:14:02Z"
}

Thread reconstruction is automatic: every reply carries the same thread_id as the original message, so your agent or handler can retrieve the full conversation context in one query without parsing In-Reply-To headers yourself.

Register a webhook — parsing starts immediately

Give each inbox its own address (or bring a custom domain), register your endpoint, and every inbound message is parsed and POSTed to you:

import Mails from "@mailsai/sdk";
const mails = new Mails({ apiKey: process.env.MAILS_API_KEY });

// One-time: register a webhook for parsed inbound events
await mails.webhooks.create({
  url: "https://your-app.com/api/email",
  events: ["message.received"],
});

// Or skip the webhook entirely — use the SSE stream or long-poll
for await (const event of mails.events.stream({ type: "message.received" })) {
  const { body_text, thread_id, injection_score, from } = event;

  // body_text is already plain-text — no HTML stripping, no MIME decoding
  if ((injection_score ?? 0) > 0.5) {
    // Treat as suspicious; skip or quarantine
    continue;
  }

  // Reply in the same thread — no Message-ID wrangling
  await mails.messages.reply(event.message_id, {
    body_text: `Hi ${from.name ?? from.address} — on it, will follow up shortly.`,
  });
}

Parsing is the product, not a feature

Unlike add-on inbound parsing from a transactional provider, the parsing layer here is first-class: multipart MIME is unwrapped, HTML is stripped to clean plain text, attachments surface as typed metadata (filename, content-type, size, inline vs. attached), and Base64-encoded bodies are decoded before delivery. When you need the raw source for auditing, it is available separately — but your handler receives the clean form by default.

Optional intent and entity classification — enabled per address or globally — adds intent, entities, and urgency fields to each parsed event at $0.003 per message. Useful when you want routing logic (high-urgency → escalate, refund-intent → billing agent) decided before your LLM runs rather than inside it.

For a deeper look at the inbound architecture — SES inbound → Lambda → structured event — see the inbound email parsing feature page.

Pricing

Parsed inbound events cost $0.002 each, including MIME handling, HTML stripping, thread reconstruction, and the injection-score scan. Intent classification is $0.003 more when enabled. The free tier covers 3,000 inbound messages per month — no card required to start. For workloads that need a dedicated address with its own MX routing, see the inbound email API for AI agents page. For outbound from the same parsed inbox, AI email agent covers the full bidirectional flow. Building the webhook handler in Python? See Email API with Webhooks for Inbound Messages — Python AI Agents for Flask and FastAPI patterns with HMAC signature verification.