MAMailagents

Mailagents

Agent-first email runtime for autonomous agents, tool-calling systems, and agent-native products.

This homepage is intentionally documentation-shaped. It is meant to be easy for an autonomous agent to parse, easy for an agent developer to integrate, and still easy for a human operator to audit.

For Agents First

If you only read one thing: sign up at https://api.mailagents.net/public/signup, read the inline accessToken from the response, then start with POST /mcp or the mailbox self routes.

Summary

Choose Your Entry Point

If you are building for an agent first, start with MCP and mailbox-scoped self routes before reaching for lower-level control paths.

HTTP API vs MCP vs SDK

Recommended By Persona

Availability And Constraints

Mailagents is usable today, but internal mailbox delivery and external-recipient delivery have different reliability profiles. Active Mailagents mailbox recipients can exchange mail through the runtime's local inbound path by default. Treat external operator-email delivery as constrained until the configured outbound provider and credit-backed outbound policy are both available for the active tenant and region.

Intended Use

Not Supported

Signup API

Agents should provision a mailbox by sending a JSON request to the signup API endpoint at https://api.mailagents.net/public/signup.

POST https://api.mailagents.net/public/signup
content-type: application/json

{
  "mailboxAlias": "agent-demo",
  "agentName": "Agent Demo",
  "operatorEmail": "operator@example.com",
  "productName": "Example Product",
  "useCase": "Handle inbound support email and send transactional replies."
}

Signup Request Fields

Signup Response

A successful signup returns mailbox metadata plus the default mailbox-scoped token inline by default. The configured operator channel remains available as a backup delivery path.

{
  "tenantId": "tnt_example",
  "mailboxAddress": "agent-demo@mailagents.net",
  "mailboxId": "mbx_example",
  "agentId": "agt_example",
  "agentVersionId": "agv_example",
  "deploymentId": "agd_example",
  "accessToken": "eyJ...",
  "accessTokenExpiresAt": "2026-04-30T00:00:00.000Z",
  "accessTokenScopes": [
    "task:read",
    "mail:read",
    "draft:create",
    "draft:read",
    "draft:send"
  ],
  "welcomeStatus": "queued"
}

Quick Start

If you want the shortest path from signup to a working agent mailbox, use this sequence.

This path intentionally prefers mailbox-scoped self routes and high-level send/reply routes first. Treat explicit draft lifecycle control as the advanced path.

  1. Call the signup API at https://api.mailagents.net/public/signup and save mailboxAddress.
  2. Read accessToken from the signup response and use it immediately.
  3. Confirm mailbox context with GET /v1/mailboxes/self.
  4. Read inbound mail with GET /v1/mailboxes/self/messages.
  5. For a first no-provider send, target another active Mailagents mailbox; those internal sends do not require external-send credits.
  6. If you plan to reach arbitrary external recipients, check GET /v1/billing/account and Limits And Access before the first external send.
  7. Send mailbox mail with POST /v1/messages/send.
  8. Keep the returned outboundJobId and poll GET /v1/outbound-jobs/{outboundJobId} until finalDeliveryState becomes sent or failed.
  9. Reply on-thread with POST /v1/messages/{messageId}/reply.
  10. Use POST /mcp and tools/list when you want the MCP tool surface instead of direct HTTP.

If the signup token expires, call POST /public/token/reissue with mailboxAlias or mailboxAddress. The runtime will email a refreshed mailbox-scoped token only to the original operatorEmail; it never returns the new token to the caller.

If the current token is still valid and the agent wants to rotate proactively without emailing the operator, call POST /v1/auth/token/rotate. That authenticated route can return the new token inline and can optionally deliver it back to the mailbox itself.

The default single-mailbox self-serve token can also be used directly for billing self-service on the same tenant, including POST /v1/billing/topup, POST /v1/billing/upgrade-intent, POST /v1/billing/payment/confirm, and the matching billing read routes.

Billing And Topup

If an external send returns an error such as External sending requires available credits, the next step is usually to top up credits on the same tenant with the mailbox-scoped token you already have. This applies to external recipients; active Mailagents mailbox recipients are delivered internally and do not require those external-send credits.

Token Lifecycle

Every new signup issues a mailbox-scoped bearer token and returns it inline by default. The configured operator channel can still receive the welcome delivery, and runtimes can explicitly disable inline return if they need that posture.

1. Sign Up

curl -sS -X POST https://api.mailagents.net/public/signup   -H 'content-type: application/json'   -d '{
    "mailboxAlias": "agent-demo",
    "agentName": "Agent Demo",
    "operatorEmail": "operator@example.com",
    "productName": "Example Product",
    "useCase": "Handle inbound support email and send transactional replies."
  }'

Save these values from the response:

2. Confirm Mailbox Context

curl -sS https://api.mailagents.net/v1/mailboxes/self   -H "authorization: Bearer $TOKEN" | jq

This is the fastest way to confirm which mailbox the current token is bound to before reading or sending mail.

3. Read Mailbox Messages

curl -sS https://api.mailagents.net/v1/mailboxes/self/messages   -H "authorization: Bearer $TOKEN" | jq

Mailbox-scoped tokens can use the self routes directly. This is the recommended first read path for product or backend integrations.

4. Send a New Email With The HTTP API

curl -sS -X POST https://api.mailagents.net/v1/messages/send   -H 'content-type: application/json'   -H "authorization: Bearer $TOKEN"   -d '{
    "to": ["recipient@example.com"],
    "subject": "Hello from Mailagents",
    "text": "Sent through the mailbox-scoped HTTP send route.",
    "idempotencyKey": "send-demo-001"
  }' | jq

Keep the accepted response. It returns outboundJobId plus statusCheck.outboundJobPath. For active Mailagents mailbox recipients, delivery routes internally; for external recipients, delivery still depends on external-send credits, policy, provider readiness, and abuse controls. Poll GET /v1/outbound-jobs/{outboundJobId} until finalDeliveryState becomes sent or failed.

5. Reply To An Inbound Message With The HTTP API

curl -sS -X POST https://api.mailagents.net/v1/messages/REPLACE_WITH_MESSAGE_ID/reply   -H 'content-type: application/json'   -H "authorization: Bearer $TOKEN"   -d '{
    "text": "Thanks for your message.",
    "idempotencyKey": "reply-demo-001"
  }' | jq

6. Discover MCP Tools

curl -sS https://api.mailagents.net/v2/meta/runtime | jq

curl -sS -X POST https://api.mailagents.net/mcp   -H 'content-type: application/json'   -H "authorization: Bearer $TOKEN"   -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }' | jq

Use MCP when you want the runtime to show its mailbox-scoped tool surface directly, including list_messages, send_email, reply_to_message, and cancel_draft.

7. Read Mailbox Messages With MCP

curl -sS -X POST https://api.mailagents.net/mcp   -H 'content-type: application/json'   -H "authorization: Bearer $TOKEN"   -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_messages",
      "arguments": {
        "limit": 10,
        "direction": "inbound"
      }
    }
  }'

8. Send A New Email With MCP

curl -sS -X POST https://api.mailagents.net/mcp   -H 'content-type: application/json'   -H "authorization: Bearer $TOKEN"   -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": ["recipient@example.com"],
        "subject": "Hello from Mailagents",
        "text": "This message was sent with the mailbox-scoped MCP tool.",
        "idempotencyKey": "send-demo-001"
      }
    }
  }' | jq

9. Reply To An Inbound Message With MCP

curl -sS -X POST https://api.mailagents.net/mcp   -H 'content-type: application/json'   -H "authorization: Bearer $TOKEN"   -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "reply_to_message",
      "arguments": {
        "messageId": "REPLACE_WITH_MESSAGE_ID",
        "text": "Thanks for your message.",
        "idempotencyKey": "reply-demo-001"
      }
    }
  }' | jq

10. Advanced Draft Control

When you need explicit lifecycle control, use the draft path as the advanced workflow:

11. Reissue An Expired Token

curl -sS -X POST https://api.mailagents.net/public/token/reissue   -H 'content-type: application/json'   -d '{
    "mailboxAlias": "agent-demo"
  }'

This endpoint always returns a generic acceptance response. If the mailbox exists, a refreshed token is delivered only to the original operatorEmail from signup.

While external outbound delivery remains limited for arbitrary external recipients, treat that path as best-effort unless the destination inbox is on a verified validation path for the active provider.

Abuse controls apply: repeated requests are cooled down per mailbox and rate limited per source IP. The API never returns the token inline.

12. Rotate A Still-Valid Token

curl -sS -X POST https://api.mailagents.net/v1/auth/token/rotate   -H 'content-type: application/json'   -H "authorization: Bearer $TOKEN"   -d '{
    "delivery": "self_mailbox",
    "mailboxId": "REPLACE_WITH_MAILBOX_ID"
  }'

This route requires a still-valid bearer token. It does not email the operator. By default it returns the rotated token inline; with delivery: "self_mailbox" or "both" it can also send the refreshed token back to the mailbox itself.

What Signup Creates

  1. One active mailbox
  2. One default agent
  3. One published default version
  4. One active mailbox deployment
  5. One default mailbox-scoped access token for read, draft, and send APIs
  6. Immediate access to MCP mailbox tools such as list_messages, send_email, and reply_to_message
  7. One welcome email through the same outbound runtime used by the product; external operator inbox delivery remains constrained by the active external provider path
  8. One public token reissue path that only emails refreshed tokens to the original operator inbox
  9. One authenticated token rotate path for agents that already hold a valid token and want to rotate without operator email

Agent Discovery

Use As A Skill

If you want a reusable agent playbook instead of parsing this homepage every time, use the canonical mailbox-agent skill in the repository: skills/mailagents-mailbox-agent/SKILL.md.

Operational Guarantees

Machine-Readable Block

service: Mailagents
category: AI-first email infrastructure
signup_mode: api_only
signup_endpoint: https://api.mailagents.net/public/signup
signup_default_access:
  token_type: bearer
  scope_model: mailbox_scoped
  default_scopes:
    - task:read
    - mail:read
    - draft:create
    - draft:read
    - draft:send
runtime_metadata: https://api.mailagents.net/v2/meta/runtime
compatibility_contract: https://api.mailagents.net/v2/meta/compatibility
fallback_contact: hello@mailagents.net
intended_use:
  - agent inbox provisioning
  - inbound email workflows
  - transactional delivery
internal_delivery:
  active_mailagents_mailboxes: local_inbound_delivery
  external_send_credits_required: false
external_delivery:
  provider: configured_runtime_provider
  credits_or_enabled_policy_required: true
unsupported_use:
  - cold outreach
  - purchased lists
  - bulk newsletters

Human Contacts

Policy Pages