Query your email from a local database

Postmesh syncs mail to local storage and exposes messages through a structured CLI and JSON interface for scripts, tools, and agents.

Install Docs
$ postmesh messages list \
--filter.from billing@example.com \
--filter.received_at.gte 2026-06-01T00:00:00Z \
--filter.query invoice
What it does

Sync mail locally, query it explicitly

Connect an email account and keep a local copy of messages, threads, labels, folders, and metadata.

DB

Sync mail locally

Keep a normalized copy of inbox data on your machine.

Q?

Query with filters

Filter by sender, recipient, subject, body text, date, state, folder, and labels.

{}

Return structured JSON

Use Postmesh from scripts, local tools, and agents without scraping an inbox UI.

Structured Query Interface

Explicit query parameters or MailQuery JSON

Postmesh accepts explicit query parameters from the CLI or a MailQuery JSON object.

postmesh messages list --filter.from notifications@example.com --filter.is_read false
postmesh -f ./mail-query.json messages list
mail-query.json
{
  "filter": {
    "from": "billing@example.com",
    "query": "invoice",
    "received_at": {
      "gte": "2026-06-01T00:00:00Z"
    }
  }
}
Built for agents

Agents layer on top of a reliable local mail retrieval API

Postmesh does not try to interpret vague instructions. It gives agents a reliable local mail retrieval layer.

1

Agent receives task

"Find unpaid invoices from last month"

2

Agent builds MailQuery

Structured filter: dates, sender, query terms

3

Postmesh returns results

Matching messages as structured JSON

4

Agent reasons over results

Summarizes, acts, or feeds into tools

Start querying mail locally

Install Postmesh, connect an account, and run a query — all from the terminal.

curl -fsSL https://postmesh.dev/install.sh | sh
$ postmesh connect --provider gmail
$ postmesh sync
$ postmesh messages list --page.limit 10