guides

Search & Intelligence

Search messages, get AI summaries, extract structured data, and configure autopilot.

Nerfmail includes a built-in intelligence layer. Every message is automatically enriched with summaries and structured data, and you can trigger on-demand analysis through dedicated endpoints.

Search

Search across messages in a mailbox:

bash

curl -X POST https://api.nerfmail.com/v1/mailboxes/{mailboxId}/search \
  -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "invoice",
    "limit": 20
  }'

Searches across subject, snippet, sender address, and message body. Results are paginated and sorted by relevance.

Message Summaries

AI-generated one-line summaries of individual messages, cached for fast retrieval.

Get a Summary

bash

curl https://api.nerfmail.com/v1/messages/{messageId}/summary \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Returns the cached summary, or 404 if not yet generated.

Generate a Summary

bash

curl -X POST https://api.nerfmail.com/v1/messages/{messageId}/summary \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

json

{
  "summary": {
    "id": "uuid",
    "message_id": "uuid",
    "summary": "Invoice #1234 from Acme Corp for $5,000 due March 30.",
    "created_at": "2026-03-16T00:00:00.000Z"
  }
}

Summaries are also generated automatically when inbound email is processed.

Structured Data Extraction

Pull structured information out of emails — invoices, receipts, confirmations, itineraries, meetings, deadlines, and contacts.

Get Extractions

bash

curl https://api.nerfmail.com/v1/messages/{messageId}/extractions \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Extract Data

bash

curl -X POST https://api.nerfmail.com/v1/messages/{messageId}/extractions \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

json

{
  "extractions": [
    {
      "id": "uuid",
      "message_id": "uuid",
      "extraction_type": "invoice",
      "data_json": "{\"invoice_number\": \"1234\", \"amount\": \"$5,000\", \"due_date\": \"2026-03-30\"}",
      "confidence": 0.92,
      "created_at": "2026-03-16T00:00:00.000Z"
    }
  ]
}

Extraction types: invoice, receipt, confirmation, itinerary, meeting, deadline, contact.

Thread Digests

AI-generated summaries of entire threads — participants, key topics, decisions, and action items.

Get a Digest

bash

curl https://api.nerfmail.com/v1/threads/{threadId}/digest \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Generate a Digest

bash

curl -X POST https://api.nerfmail.com/v1/threads/{threadId}/digest \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

json

{
  "digest": {
    "id": "uuid",
    "thread_id": "uuid",
    "digest": "3-message thread between alice@example.com and bob@nerfmail.com discussing Q2 budget. Key decision: approved $50k allocation. Action item: Bob to send revised projections by Friday.",
    "message_count": 3,
    "created_at": "2026-03-16T00:00:00.000Z"
  }
}

Digests are automatically refreshed when the thread has new messages since the last digest.

Sender Intelligence

AI-analysed relationship context for people who email you — relationship type, common topics, and sentiment.

Get Intelligence

bash

curl https://api.nerfmail.com/v1/sender-profiles/{profileId}/intelligence \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Generate Intelligence

bash

curl -X POST https://api.nerfmail.com/v1/sender-profiles/{profileId}/intelligence \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

json

{
  "intelligence": {
    "id": "uuid",
    "sender_profile_id": "uuid",
    "relationship_type": "vendor",
    "ai_summary": "Regular vendor contact sending monthly invoices and quarterly reports.",
    "topics_json": "[\"billing\", \"reports\", \"contracts\"]",
    "sentiment": "neutral",
    "created_at": "2026-03-16T00:00:00.000Z"
  }
}

Autopilot

Autopilot lets you define rules that automatically act on incoming email.

Get Policy

bash

curl https://api.nerfmail.com/v1/mailboxes/{mailboxId}/autopilot \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Set Rules

bash

curl -X PUT https://api.nerfmail.com/v1/mailboxes/{mailboxId}/autopilot \
  -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "enforce",
    "rules": [
      {
        "condition": "triage_label == newsletter",
        "action": "archive"
      },
      {
        "condition": "risk_level == critical",
        "action": "flag"
      }
    ]
  }'

Mode	Behaviour
`observe`	Rules are evaluated but no actions are taken (default)
`enforce`	Rules are evaluated and actions are executed automatically

Start in observe mode to see what would happen, then switch to enforce when you're confident in your rules.

PreviousDrafts & Labels

NextOpenClaw Integration