Add an email address or domain to an inbox-scoped allow/block list via AgentMail's MPP API.
What it does
This endpoint creates a new entry in an inbox-scoped allow or block list on AgentMail, an email inbox platform designed for AI agents. The path parameters let you specify the inbox ID, the direction of the rule (send, receive, or reply), and the list type (allow or block). The request body accepts an email address or domain string along with an optional reason.
AgentMail exposes a comprehensive email API covering inboxes, messages, threads, drafts, domains, webhooks, and sender/receiver lists. This particular "Create List Entry" operation is scoped to a single inbox within a pod, letting agents programmatically manage which addresses or domains are permitted or blocked for that inbox. The endpoint uses MPP (Micropayment Protocol) for payment at a fixed price of $0.01 per call. Authentication is via Bearer token in the Authorization header.
The OpenAPI spec defines the response schema as a `PodListEntry` object containing the entry value, pod_id, optional inbox_id, direction, list_type, entry_type (email or domain), organization_id, created_at timestamp, and an optional reason field. Validation errors return a 400 with structured error details. The broader AgentMail API also supports creating inboxes ($2.00), sending messages ($0.01), custom domains ($10.00), and more, all via MPP.
Capabilities
Use cases
- —Block spam domains from reaching an AI agent's inbox
- —Allow only specific sender addresses to deliver to an agent inbox
- —Restrict outbound sends from an inbox to approved recipients
- —Programmatically manage reply-allowed addresses for automated correspondence
- —Build agent workflows that dynamically update inbox filtering rules
Fit
Best for
- —AI agents that need per-inbox email filtering rules
- —Automated systems managing multiple agent inboxes with distinct allow/block policies
- —Developers building agent-to-human email workflows with access control
Not for
- —Bulk email marketing or mass mailing operations
- —Human-facing email clients that need a full GUI inbox experience
- —Non-email communication channels (SMS, chat, etc.)
Quick start
curl -X POST "https://mpp.api.agentmail.to/v0/inboxes/{inbox_id}/lists/receive/block" \
-H "Authorization: Bearer $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",
"pod_id": "pod_abc123",
"reason": "Known spam sender",
"inbox_id": "inbox_xyz789",
"direction": "receive",
"list_type": "block",
"created_at": "2025-01-15T12:00:00Z",
"entry_type": "email",
"organization_id": "org_def456"
}Endpoint
Quality
Full OpenAPI schema with detailed component definitions and clear pricing ($0.01 per call). However, the probe did not capture a live 402 MPP challenge for this specific endpoint (returned 404 on HEAD, 403 on GET — POST was not probed), and no external documentation pages were reachable from the MPP gateway. The response schema is inferred from referenced components.
Warnings
- —Probe did not capture a 402 MPP challenge for this endpoint; POST method was not attempted during probing
- —No dedicated documentation pages were reachable at the MPP gateway origin — docs are at docs.agentmail.to
- —Price of $0.01 is from x-payment-info in the OpenAPI spec; actual MPP challenge was not verified at runtime
Citations
- —The Create List Entry endpoint has a fixed MPP price of 0.010000https://mpp.api.agentmail.to
- —Direction enum values are send, receive, reply; ListType enum values are allow, blockhttps://mpp.api.agentmail.to
- —AgentMail is the email inbox API for AI agentshttps://mpp.api.agentmail.to
- —AgentMail raised $6M in Seed Fundinghttps://mpp.api.agentmail.to