Cookbook
Triage incoming mail
Scan, classify, escalate, and forward physical mail received at the registered agent. Webhook-driven.
Last updated
Scan, classify, escalate, and forward physical mail received at the registered agent. Webhook-driven.
Trigger
Mail lands at the registered agent.
Call sequence
1. Subscribe to mail.received
// webhook2. Classify
POST /v1/mail/{id}/categorize { category: 'tax_notice' }3. Escalate or forward as needed
POST /v1/mail/{id}/escalateIdempotency
Categorization idempotent on `(mail, category)`.
Webhooks
| Event | Description |
|---|---|
mail.received | New piece scanned. |
mail.escalated | Routed to a human. |
mail.forwarded | Physical forwarded. |
Categories
The classifier runs on every scan and assigns one of these category
values:
category | What it is | Default routing |
|---|---|---|
service_of_process | Lawsuits, summons, subpoenas, tax-court notices. | escalate to oncall (HITL-required). |
court_filing | Court orders, default-judgement notices, garnishment orders. | escalate to legal counsel. |
tax_notice | IRS / state DOR notices, franchise-tax invoices, sales-tax assessments. | forward to CPA, attach to Filing if matched. |
state_notice | Annual-report reminders, foreign-qualification renewals, BOI confirmations. | forward to compliance, attach to Filing if matched. |
bank | Bank statements, signature-card requests, KYC follow-ups. | forward to founder, archive. |
vendor | Insurance bills, software-renewal invoices, RA correspondence from third-parties. | forward to ops, acknowledge. |
junk | Solicitations, fake-government-look-alike mailers, marketing. | acknowledge and archive. |
other | Anything the classifier can't place with high confidence. | Surface to a human; let them re-categorize. |
Re-categorize via POST /v1/mail/{id}/categorize if the classifier was
wrong; the category_confidence field on MailItem tells you when to
second-guess.
Service-of-process is always HITL. Even with a tier-4 token holding
mail.acknowledge, the API enforces an SOP guard that escalates every
service_of_process item to a human signature regardless of policy.
Limits like deny_acknowledge_when: "category == 'service_of_process'"
on the token are belt-and-braces with the API's hard floor.
Variations
For agents that should pause on every mutation but iterate fast in test
mode, use a tier-3 token with auto_approve: true at token creation.
Every action the agent takes still creates an Authorization, but it
flips to approved within ~50ms in test mode. Production keeps the
human-in-the-loop. See test mode for agents.
When mail.received fires with related_filing_id populated, the
inbound notice has been matched to a known obligation. Pay the amount
via the matched filing rather than treating the mail item as a separate
task:
curl -X POST https://api.mattermode.com/v1/filings/flg_de_franchise_2025/pay \
-H "Authorization: Bearer $MATTER_KEY" \
-H "Matter-Version: 2026-05-01" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"source_mail_id": "mail_F2sQwLtR"}'The mail.acknowledged webhook fires automatically once the filing
payment clears.
By default, junk items stay in acknowledged state for 90 days before
auto-archiving. Tighten this for entities with high-volume
registered-agent addresses by setting a per-entity policy:
curl -X PATCH https://api.mattermode.com/v1/entities/ent_Nq3KcAbc \
-H "Authorization: Bearer $MATTER_KEY" \
-H "Matter-Version: 2026-05-01" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"mail_policy": {"junk_archive_after_days": 7}}'For mail that needs a typed response (e.g., a state DOR information
request that asks for clarification on a return), use respond to draft
a reply that Matter prints, signs, and mails back via certified mail:
curl -X POST https://api.mattermode.com/v1/mail/mail_F2sQwLtR/respond \
-H "Authorization: Bearer $MATTER_KEY" \
-H "Matter-Version: 2026-05-01" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"response_text": "We have reviewed your notice dated 2026-04-12 and confirm that the entity remains in good standing. Please find enclosed the requested supporting schedule for the 2025 tax year.",
"attachments": ["doc_2025_schedule_c"],
"delivery": {"method": "certified_mail"}
}'The endpoint creates a child Document with attaches_to: <inbound mail's scan_document_id> and attachment_kind: response_letter, signs
it as the entity's authorized officer, and mails it. The response
document plus the certified-mail tracking number land on
MailItem.response_document_id and
MailItem.forwarding.tracking_number.
Related
- Mail endpoint — primitive reference
- Filings —
related_filing_idmatching - Run a board consent — for governance-affecting court orders