---
title: "Extract the fields you need from a message with your own schema"
method: POST
path: "/api/emails/{address}/messages/{id}/extract"
tags: ["Mailzero Assistant"]
---

# Extract the fields you need from a message with your own schema

`POST /api/emails/{address}/messages/{id}/extract`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/emails/{address}/messages/{id}/extract`
- Auth: HTTP bearer

One model call on the message text (subject, sender, body) with a caller JSON schema of objects and primitives (up to 8 KB, no references): answers `data` in that shape, `confidence` (0 to 1) and `evidence_quotes` (verbatim excerpts). Cached by (message, schema, instructions) so the same question costs one call (`cached: true` after). Gated by the account's model budget (429 when spent, 503 when the model route is off). Sign-in code mails answer 403 AUTH_MESSAGE. Bodies over 60,000 characters answer 413.

## Path parameters

- `address` string, required
- `id` string, required

## Request body

- object
  - `schema` object, required: JSON schema of the fields to extract: an object of primitives, arrays and nested objects, under 8 KB, no $ref
  - `instructions` string: Optional guidance, e.g. amounts in EUR

## Response `200`

The extracted fields

- object
  - `message_id` string, required
  - `data` object, required
  - `confidence` number, required
  - `evidence_quotes` string[], required
  - `model` string, required
  - `cached` boolean, required
  - `generated_at` string, date-time, required
  - `usage` object
    - `input_tokens` integer
    - `output_tokens` integer
    - `latency_ms` integer

## Other responses

- `400`: Schema rejected (INVALID_SCHEMA)
- `401`: Missing or invalid API key
- `403`: Sign-in code mail (AUTH_MESSAGE)
- `404`: Mailbox or message not found
- `413`: Schema or message too large
- `429`: Rate limit exceeded - wait and retry
- `503`: Model route not configured

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)