Create a custom email domain for an AI agent pod via the AgentMail MPP API.
What it does
This endpoint creates a custom domain within a specific pod on the AgentMail platform. AgentMail provides email inboxes purpose-built for AI agents, and this particular route (`POST /v0/pods/{pod_id}/domains`) lets you register a new domain under a given pod so that inboxes can send and receive email on that domain. The endpoint is part of a comprehensive REST API that also covers inbox creation, message sending/receiving, threads, drafts, webhooks, allow/block lists, and metrics.
The endpoint is served over the MPP (Micropayment Protocol) gateway at `mpp.api.agentmail.to`. It settles payments via the Tempo method on chain ID 4217. According to the OpenAPI spec, creating a domain is priced at a fixed 10.000000 units (the currency and decimals are not fully specified in the challenge for this particular route, but the broader API prices other operations in similar decimal notation). The request body requires a `domain` name (e.g. "example.com") and a `feedback_enabled` boolean that controls whether bounce and complaint notifications are sent to your inboxes. On success, the API returns a Domain object containing the domain ID, verification status, required DNS records, and timestamps.
The GET variant on the same path lists all domains in a pod and is free (price 0). Related operations include verifying a domain (`POST .../verify`), retrieving its DNS zone file, updating feedback settings, and deleting the domain. Authentication is via Bearer token in the Authorization header.
Capabilities
Use cases
- —Register a branded custom domain so AI agents send email from your-company.com instead of agentmail.to
- —Provision per-tenant email domains in a multi-tenant AI agent platform
- —Automate domain setup as part of an agent onboarding workflow
- —Enable bounce and complaint feedback routing to agent inboxes on a custom domain
Fit
Best for
- —AI agent builders who need branded outbound email
- —Platforms provisioning isolated email domains per customer or agent pod
- —Developers integrating email capabilities into autonomous agents
Not for
- —Human-facing webmail or consumer inbox products
- —Bulk marketing email sending (this is an infrastructure API, not an ESP)
- —Use cases requiring free domain creation (each domain costs a fixed fee)
Quick start
curl -X POST https://mpp.api.agentmail.to/v0/pods/{pod_id}/domains \
-H "Authorization: Bearer <MPP_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"domain": "example.com", "feedback_enabled": true}'Example
Request
{
"domain": "example.com",
"feedback_enabled": true
}Response
{
"pod_id": "pod_abc123",
"status": "NOT_STARTED",
"records": [
{
"name": "_agentmail.example.com",
"type": "TXT",
"value": "v=agentmail1 ...",
"status": "MISSING"
},
{
"name": "example.com",
"type": "MX",
"value": "mx.agentmail.to",
"status": "MISSING",
"priority": 10
}
],
"domain_id": "example.com",
"created_at": "2025-01-15T12:00:00Z",
"updated_at": "2025-01-15T12:00:00Z",
"feedback_enabled": true
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed component definitions is available and the MPP 402 challenge was captured live, confirming the endpoint is operational. Price units and currency decimals for this specific endpoint are not fully clarified in the challenge (the GET probe returned amount 0), so the exact dollar cost of domain creation is inferred from the OpenAPI x-payment-info field (10.000000) rather than a live POST challenge. Documentation pages on the MPP gateway itself return 404, so external docs are not directly available in the crawl.
Warnings
- —The currency token address in the MPP challenge (0x20C0...8b50) and its decimals are not explicitly documented; the fixed price of 10.000000 from the OpenAPI spec may represent $10 if the token uses 6 decimals, but this is not confirmed.
- —No dedicated documentation pages were reachable on the MPP gateway; refer to https://docs.agentmail.to/ for full docs.
- —The example response is synthesized from the OpenAPI schema, not captured from a live call.
Citations
- —The endpoint POST /v0/pods/{pod_id}/domains has a fixed price of 10.000000 per the OpenAPI x-payment-info field.https://mpp.api.agentmail.to
- —The CreateDomainRequest requires 'domain' and 'feedback_enabled' fields.https://mpp.api.agentmail.to
- —AgentMail raised $6M in Seed Funding and is backed by Y Combinator.https://mpp.api.agentmail.to
- —The MPP challenge confirms the endpoint is live, settling via Tempo method on chain ID 4217.https://mpp.api.agentmail.to
- —Domain verification statuses include NOT_STARTED, PENDING, INVALID, FAILED, VERIFYING, and VERIFIED.https://mpp.api.agentmail.to