# Mail Developer API (dev.txnal.com)

> Developer API and AI Agent interface for Mail (Inbox Control & Transactional Data Extraction)

The Mail Developer API powers inbox management, email thread triage, transactional receipt/order data extraction, drafts, and full-text search. This documentation is structured for autonomous AI agents, tool builders, and LLM context loading.

- **Version**: 1.60
- **Base Production URL**: `https://mail.txnal.com`
- **Developer Portal**: `https://dev.txnal.com`
- **Local Development URL**: `http://localhost:3000`

## Core Concepts

- [Authentication](https://dev.txnal.com/llms-full.txt#authentication): Two-tier JWT token exchange. Clients exchange a 7-day refresh token for a short-lived 5-minute access token (`POST /api/v1/auth/token`).
- [Authorization Headers](https://dev.txnal.com/llms-full.txt#headers): Authenticated requests require `Authorization: Bearer <access_token>`.
- [Permissions](https://dev.txnal.com/llms-full.txt#permissions): All endpoints require the `user_api` permission flag on the authenticated user.
- [Error Handling](https://dev.txnal.com/llms-full.txt#errors): All non-2xx responses return JSON with `{ "error": "...", "message": "..." }`.

## API Endpoints

- [Authentication Endpoints](https://dev.txnal.com/llms-full.txt#authentication):
  - `POST /api/v1/auth/token`: Mint/rotate access tokens.
  - `POST /api/v1/auth/tokens`: Alias for token exchange.
  - `POST /api/v1/auth/rotate`: Alias for token rotation.
  - `POST /api/v1/auth/revoke`: Revoke active client session.
  - `DELETE /api/v1/auth/revoke`: Revoke active client session.
- [User Profile](https://dev.txnal.com/llms-full.txt#user-profile):
  - `GET /api/v1/me`: Inspect user details, preferences, permissions, and connected email accounts.
- [Emails & Threads](https://dev.txnal.com/llms-full.txt#emails):
  - `GET /api/v1/emails`: List and filter emails (bundle, seen, snoozed, category, starred).
  - `GET /api/v1/emails/{id}`: Detailed message view including parsed transactional data fields.
  - `GET /api/v1/emails/{id}/thread`: Chronological conversation thread with all replies.
  - `PATCH /api/v1/emails/{id}/triage`: Triage message (read state, star, snooze, bundle assignment, category).
  - `POST /api/v1/emails/send`: Direct email message queueing and delivery.
- [Drafts](https://dev.txnal.com/llms-full.txt#drafts):
  - `GET /api/v1/drafts`: List active drafts.
  - `POST /api/v1/drafts`: Create new draft.
  - `GET /api/v1/drafts/{id}`: Get draft details.
  - `PATCH /api/v1/drafts/{id}`: Update draft.
  - `DELETE /api/v1/drafts/{id}`: Delete draft.
  - `POST /api/v1/drafts/{id}/send`: Send existing draft.
- [Bundles](https://dev.txnal.com/llms-full.txt#bundles):
  - `GET /api/v1/bundles`: List user bundles and unseen message counts.
- [Search](https://dev.txnal.com/llms-full.txt#search):
  - `GET /api/v1/search`: Query-based email and entity search.
  - `GET /api/v1/search/suggestions`: Auto-complete search suggestions by prefix.

## Machine-Readable Specifications

- [Full Markdown Reference (llms-full.txt)](https://dev.txnal.com/llms-full.txt): Complete, detailed endpoint specifications, query schemas, and payload examples.
- [OpenAPI Specification (JSON)](https://dev.txnal.com/openapi.json): Raw OpenAPI 3.1.0 schema for agent tool use, dynamic function calling, and client generation.
- [OpenAPI Specification (YAML)](https://dev.txnal.com/openapi.yaml): Raw OpenAPI 3.1.0 schema in YAML format.