nerfmail
nerfmail

guides

Inbound Email

How Nerfmail receives, assesses, and enriches incoming email.

Every email sent to a Nerfmail address is automatically received, parsed, and enriched with risk assessment and AI intelligence. You can query the results through the API.

How It Works

When an email arrives at any of your mailbox addresses:

  1. The message is received and stored
  2. It's parsed — body, headers, attachments are extracted
  3. Risk assessment runs automatically
  4. AI enrichment adds summaries, labels, and structured data
  5. Webhooks fire so your systems are notified

The entire process happens asynchronously. Your senders see a successful delivery immediately.

Risk Assessment

Every inbound message is scored for risk. The assessment produces a risk level and a triage label you can filter on.

Risk Levels

Level Meaning
low Normal message
medium Some suspicious signals
high Multiple risk factors
critical Likely malicious or sender is blocked

Triage Labels

Label Meaning
routine Normal low-risk message
newsletter Bulk or list mail
needs-review Medium risk — may need human attention
fraud-risk High or critical risk
auto-reply Automated response (out-of-office, etc.)
blocked Sender has been blocked

What Gets Flagged

Signal Severity Trigger
Unknown sender Low First message from this address
Reply-To mismatch High Reply-To domain differs from From domain
Urgency + credential keywords High Phishing-style language patterns
Risky attachment types High .exe, .js, .html, .zip, macro-enabled Office files
Punycode domain Medium Internationalised domain encoding (potential spoofing)
Many links Low 5 or more links in the message
Newsletter detected Reduces score List-ID or List-Unsubscribe headers present

Sender Profiles

Nerfmail tracks senders automatically. Each sender profile records:

  • Display name from the From header
  • Disposition — neutral (default), trusted, or blocked
  • Message count and last seen timestamp

Blocked senders are automatically flagged as critical risk. Trusted senders skip the unknown-sender signal.

You can manage sender dispositions through the API:

bash
curl -X POST https://api.nerfmail.com/v1/accounts/{accountId}/sender-profiles \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "trusted@partner.com",
    "disposition": "trusted"
  }'

AI Enrichment

After a message is processed, Nerfmail automatically:

  1. Auto-labels — Classifies the message into categories (e.g., auto:finance, auto:travel)
  2. Generates a summary — A one-line AI summary, cached for fast retrieval
  3. Extracts structured data — Pulls out invoices, meetings, deadlines, contacts, and more

All enrichment is non-blocking — if it can't run, your message is still processed normally.

See Search & Intelligence for on-demand intelligence endpoints.

Message Statuses

Status Meaning
queued Received, being processed
processed Parsed, assessed, and ready
responded A reply has been sent
archived Archived by the mailbox owner
reviewed Marked as reviewed

Querying Messages

bash
curl "https://api.nerfmail.com/v1/mailboxes/{mailboxId}/messages?\
status=processed&\
direction=inbound&\
triage_label=needs-review&\
limit=20" \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Available filters: status, direction, transport, triage_label, risk_level, query (subject search).

PreviousSending Email
NextAgent Protocol