Skip to content
Use Case

Email to JSON API

Turn raw email into typed, schema-validated JSON with a single POST. No regex. No parsing rules. Use a pre-built schema_id or an inline JSON Schema, a bearer token, and the raw MIME text — MailFrame returns structured data you can write straight to your database.

Parsing email is harder than it looks

Emails are not clean data. Every message arrives as a MIME tree — nested multipart containers, base64-encoded bodies, HTML and plain-text alternatives, inline attachments, and character-set declarations that are routinely wrong. A single multipart/mixed message can have five layers of nesting before you reach the content you actually want.

Hand-rolling a parser means maintaining regular expressions that break on real-world edge cases, handling transfer encodings yourself, and building validation logic that catches malformed output before it poisons your database. It works on your test corpus and silently fails in production when a vendor changes their email template.

MailFrame replaces all of that with a single API call. You describe the fields you want in JSON Schema — their names, types, and constraints. MailFrame extracts against your schema, validates the result, and hands you back typed JSON that is validated against the shape you defined.

Schema-first, not regex-first

Most email parsers ask you to write extraction rules — patterns, selectors, or templates that map messy email bodies onto fields. When the upstream template changes, your rules break and you rebuild them.

MailFrame inverts this: you define the output shape as a JSON Schema document. The extraction is validated against it automatically, so malformed results never land in your database. If a required field is missing or a value is the wrong type, you get validation_errors back immediately and you handle the failure explicitly.

This is the same contract you already have with every REST API you consume: define the schema, get validated data back, trust the types. Applied to email.

Request & response example

Send a raw MIME email with a schema_id or inline JSON Schema to POST /v1/parse. MailFrame returns typed, validated JSON in the same HTTP response.

1. Define your schema

JSON Schema 
{
  "title": "stripe_receipt",
  "type": "object",
  "required": ["amount_cents", "currency"],
  "properties": {
    "amount_cents": { "type": "integer" },
    "currency":     { "type": "string" },
    "card_last4":   { "type": "string", "pattern": "^[0-9]{4}$" }
  }
}

2. POST raw MIME 

curl -X POST https://api.mailframe.ai/v1/parse \
  -H "Authorization: Bearer $MAILFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "stripe_receipt",
    "raw_mime": "From: billing@stripe.com\r\nTo: dev@example.com\r\nSubject: Your Stripe Receipt\r\n\r\nThank you for your payment of $29.99."
  }'
const res = await fetch("https://api.mailframe.ai/v1/parse", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILFRAME_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    schema_id: "stripe_receipt",
    raw_mime: rawMimeText,
  }),
});

const { data, status, validation_errors } = await res.json();
import os
import requests

res = requests.post(
    "https://api.mailframe.ai/v1/parse",
    headers={"Authorization": f"Bearer {os.environ['MAILFRAME_API_KEY']}"},
    json={
        "schema_id": "stripe_receipt",
        "raw_mime": raw_mime_text,
    },
)
res.raise_for_status()
body = res.json()

3. Receive validated JSON

200 response 
{
  "id": "parse_8f2a1c",
  "status": "completed",
  "validation_errors": [],
  "data": {
    "amount_cents": 2999,
    "currency": "usd",
    "card_last4": "4242"
  }
}

The data field is validated against your schema with its types and constraints. Write it straight to your database.

What developers build with MailFrame

E-commerce receipts

Parse Stripe, Shopify, PayPal, and Amazon order confirmation emails into structured line items, totals, and payment details for automated bookkeeping and reconciliation.

Customer support triage

Extract sender identity, subject, priority signals, and body text from inbound support emails so your ticketing system routes and categorises with zero manual tagging.

Notification & alert pipelines

Turn GitHub, Datadog, PagerDuty, or custom alert emails into typed webhook payloads that your internal tooling can act on reliably — no brittle text parsing.

Lead capture & CRM ingestion

Accept forwarded inquiry emails and extract contact fields, company name, and message content directly into your CRM or lead-routing system.

Invoice & PO processing

Pull invoice numbers, vendor names, line items, and totals out of supplier emails and route them into your AP workflow or ERP automatically.

DevOps automation

Parse build failure notifications, certificate expiry warnings, and scheduled report emails so your internal automation can trigger the right remediation without a human in the loop.

How to get started

  1. 1

    Request access & get your API key

    Request early access — MailFrame onboards developers in weekly batches. Once you receive your key, store it in your secret manager and never in source control.

  2. 2

    Define your JSON Schema

    Pick one from the schema library or register your own through the API. The schema describes the fields you want — MailFrame validates every extraction against it.

  3. 3

    POST raw MIME to /v1/parse

    Send the raw RFC 822 MIME text of an email alongside your schema ID. MailFrame answers the same request with the validated result — no polling, no callback required. For async delivery, webhooks are available in early access.

  4. 4

    Check the response & store

    Inspect the status and validation_errors fields. When the parse completed cleanly, the data payload is already typed and schema-valid — write it directly into your database or queue.

Frequently asked questions

What email formats can MailFrame parse?

MailFrame accepts raw RFC 822 MIME text — the wire format of every email. You POST it directly to /v1/parse and receive typed, schema-validated JSON in the synchronous HTTP response. Multipart messages, nested MIME parts, and common transfer encodings (base64, quoted-printable) are all handled. PDF and image input are on the roadmap.

How is MailFrame different from writing my own email parser?

Building a robust email parser means wrestling with MIME boundary parsing, charset detection, nested multipart trees, and regular expressions that break on real-world edge cases. MailFrame replaces that with a single API call: you define a JSON Schema describing the fields you want, we return validated typed JSON. No regex maintenance, no parser rewrites when upstream email templates change, no charset heisenbugs.

What does 'schema-first' mean in practice?

You define exactly what fields you want back using JSON Schema — their names, types, required/optional status, and constraints (min/max, patterns, enums). MailFrame extracts against that schema and validates the result before returning it. If the extraction violates your schema (a required field is missing, a value is the wrong type), you get validation_errors back so you can handle the failure explicitly instead of discovering bad data downstream.

Can I use my own JSON Schema or just the built-in ones?

Both. MailFrame ships a growing library of pre-built schemas for Stripe receipts, Shopify orders, GitHub notifications, PayPal receipts, and more. You can also register your own schemas through the API or dashboard — they are scoped to your account and MailFrame validates extractions against them on every parse.

How are parse results delivered?

Results are returned synchronously in the HTTP response to your POST /v1/parse request. The response body includes the typed data payload, the parse status, and any schema validation errors — everything you need to decide whether to write to your database. Signed webhook delivery (HMAC-SHA256, with retries, delivery history, and a dead-letter queue) is available in early access for teams that prefer asynchronous delivery.

Is there a free tier so I can try it?

Yes — the Free tier includes 100 parse operations per month, no credit card required. You can also try the Stripe receipt parser tool directly in your browser without signing up.

What programming languages does MailFrame support?

MailFrame is a REST API — you call it over HTTPS with a bearer token, so it works with any language that can make HTTP requests. The docs ship copy-paste examples in curl, TypeScript, and Python for every endpoint.

Ready to turn email into typed JSON?

Define a JSON Schema, POST your raw email, get validated data back. Start with 100 free parse operations per month — no credit card.

Request early access Read the docs