Add email allow/block list entries for AI agent inboxes via MPP-paid API calls.
What it does
This endpoint is part of the AgentMail MPP gateway, which provides programmatic email inbox management for AI agents. The specific route `POST /v0/lists/{direction}/{type}` creates a new list entry at the organization level, allowing you to add email addresses or domains to allow or block lists for send, receive, or reply directions. A parallel endpoint exists scoped to individual inboxes and pods.
The API uses MPP (Micropayment Protocol) with Tempo settlement on chain ID 4217. Creating a list entry costs a fixed price of $0.01 per call (the x-payment-info shows price "0.010000"). Read operations (GET, list entries) are priced at $0.00. The request body requires an `entry` field (email address or domain) and an optional `reason` string. Path parameters `direction` (send, receive, reply) and `type` (allow, block) determine which list the entry is added to. Bearer authentication is required via the Authorization header.
AgentMail is a YC-backed company that raised $6M in seed funding. The broader API surface covers inbox creation, message sending/receiving, threads, drafts, attachments, webhooks, custom domains, pods, and metrics — all accessible through the same MPP gateway at mpp.api.agentmail.to.
Capabilities
Use cases
- —Block spam domains from reaching an AI agent's inbox
- —Allow only specific sender addresses for a customer-support agent
- —Restrict outbound sends to approved recipient domains
- —Manage per-inbox or organization-wide email filtering rules
- —Programmatically update block lists in response to detected abuse
Fit
Best for
- —AI agents that need programmatic email filtering
- —Automated inbox management workflows
- —Multi-tenant agent platforms needing per-pod or per-inbox list control
Not for
- —Human-facing email client features (no UI)
- —Bulk email marketing or newsletter management
- —Non-email communication channels
Quick start
curl -X POST 'https://mpp.api.agentmail.to/v0/lists/receive/block' \
-H 'Authorization: Bearer <MPP_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"entry": "spam@example.com", "reason": "Known spam sender"}'Example
Request
{
"entry": "spam@example.com",
"reason": "Known spam sender"
}Response
{
"entry": "spam@example.com",
"direction": "receive",
"list_type": "block",
"created_at": "2025-01-15T12:00:00Z",
"entry_type": "email",
"organization_id": "org_abc123"
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed component definitions, live 402 MPP challenge captured, clear pricing in x-payment-info. Docs pages on the MPP gateway itself return 404, but the OpenAPI spec is comprehensive. Response examples are inferred from schema rather than captured live.
Warnings
- —No dedicated documentation pages served from the MPP gateway (docs/api/pricing all return 404)
- —Response example is inferred from the OpenAPI ListEntry schema, not from a live 200 response
- —Currency address 0x20C0...8b50 on chain 4217 (Tempo) — exact token not independently verified but consistent with pathUSD (6 decimals)
Citations
- —AgentMail raised $6M in Seed Fundinghttps://mpp.api.agentmail.to
- —Create List Entry endpoint has fixed price of 0.010000 via MPPhttps://mpp.api.agentmail.to
- —Direction enum values are send, receive, reply; ListType enum values are allow, blockhttps://mpp.api.agentmail.to
- —MPP challenge uses method tempo with chainId 4217 and intent chargehttps://mpp.api.agentmail.to
- —CreateListEntryRequest requires entry (string) and optional reason (string)https://mpp.api.agentmail.to
- —ListEntry response includes entry, organization_id, direction, list_type, entry_type, created_athttps://mpp.api.agentmail.to