Email API for AI agents

An agent can own an address that receives mail. Tillpad does not send mail from that address. For developers giving an agent its own inbox. Pro is $9 a month.

Create an inbox

POST /api/inboxes creates an address on the account's inbound domain. GET /api/config returns that domain as inboundEmailDomain. The production default in this deployment is centralmail.us. localPart is stored lowercased. It must be 1 to 64 characters, letters, digits, and . _ - , and it cannot start or end with a special character.

kind is temporary or permanent. A temporary inbox expires after ttlSeconds. The default is 86400 seconds and the maximum is 604800 seconds unless the deployment overrides those. When it expires, stored messages are purged. A permanent inbox does not expire. An account can have 50 active inboxes.

Creating an inbox requires an active plan. The create call itself does not meter. Each accepted message later meters one inbound_email.

curl -s -X POST "https://tillpad.dev/api/inboxes" \
  -H "Authorization: Bearer tp_…" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"agent-jobs","kind":"temporary","ttlSeconds":86400}'

Read mail, webhooks, and blocks

Give the agent an address, and mail that arrives is stored for it to read. GET /api/inboxes/:id/messages lists metadata, newest first. GET one message returns it plus the attachment list. Those reads do not spend quota. GET .../raw returns the raw MIME as base64 and meters one kvp_ops. GET an attachment returns the bytes as base64 and meters one kvp_ops.

  • 100 accepted messages per hour
  • 20 attachments per message
  • 10 MB per attachment
  • 25 MB of raw MIME
  • 10 messages per minute from one sender

Webhooks and blocks

POST /api/inboxes/webhooks registers an HTTPS URL for email.received. The POST body is metadata, not the message body, and it is HMAC signed. The signing secret is returned once if you do not pass one. Delivery failures after retries are listed at GET /api/inboxes/webhooks/failures.

POST /api/inboxes/blocklist blocks one sender address or a whole domain for every inbox on the account. The blocklist holds up to 500 entries. MCP tools for the same work are manage_inbox, read_inbox_message, manage_inbox_webhook, and manage_inbox_blocklist.

Related

Questions people ask

Can the agent send email?

No. Inboxes are receive-only. There is no send endpoint and the MCP inbox tools do not send mail.

Does the webhook include the message body?

No. The email.received webhook is metadata only. Read the message with the inbox message APIs.