Frequently Asked Questions

General

What is AgentPost?

AgentPost is a self-hosted email infrastructure platform designed for AI agents. It provides a REST API, TypeScript and Python SDKs, and an MCP server for programmatically creating inboxes, sending and receiving email, managing threads, and handling real-time events through webhooks and WebSockets.

How is AgentPost different from AgentMail?

AgentPost is an open-source, self-hosted alternative to AgentMail.to. While AgentMail is a managed SaaS service, AgentPost runs on your own infrastructure. This means:

• No per-inbox costs -- Create as many inboxes as you need
• No artificial limits -- Your limits are your infrastructure's limits
• Data sovereignty -- All email data stays on your servers
• Customizable -- Fork and modify to fit your exact needs

Is AgentPost free?

Yes. AgentPost is open-source and free to self-host. Your costs are limited to the infrastructure you run it on (server, database, AWS SES for email delivery). There is no licensing fee, per-inbox charge, or usage-based pricing from AgentPost itself.

What are the self-hosting requirements?

AgentPost requires:

• Node.js 20+ -- Runtime for the API server
• PostgreSQL 16+ -- Primary database
• AWS SES -- Email sending and receiving
• Cloudflare R2 (or S3-compatible) -- Attachment storage
• Docker (recommended) -- For containerized deployment

Minimum recommended specs: 2 CPU cores, 4GB RAM, 20GB storage.

Email

Which email providers does AgentPost support?

Currently, AgentPost uses AWS SES (Simple Email Service) as its email provider for both sending and receiving. SES is reliable, cost-effective, and handles the complexities of email delivery infrastructure.

Support for additional providers (SendGrid, Postmark, Mailgun) is on the roadmap but not yet implemented.

What is the maximum message size?

AgentPost supports messages up to 10 MB including attachments. This is consistent with the AWS SES size limit. Larger attachments should be hosted externally and linked in the email body.

Does AgentPost support HTML emails?

Yes. When sending a message, you can provide both text_body (plain text) and html_body (HTML). AgentPost sends a multipart MIME message that email clients render based on their capabilities. Always include a plain text fallback for accessibility and deliverability.

How does AgentPost handle bounces and complaints?

AgentPost receives bounce and complaint notifications from AWS SES via SNS (Simple Notification Service). These are:

1. Stored as delivery events in the database
2. Emitted as message.bounced and message.complained webhook events
3. Used to calculate the deliverability score for each inbox
4. Used to auto-pause inboxes that exceed bounce rate thresholds

See Email Deliverability for details.

API

How are API keys managed?

API keys are created through the API or web console. Each key:

• Has a prefix of ap_sk_ followed by an environment indicator (live_, dev_, test_)
• Can be scoped to specific permissions (e.g., inboxes:read, messages:write)
• Can be restricted to specific environments
• Is hashed before storage (the full key is shown only once at creation)

What are the rate limits?

Rate limits depend on your organization's tier:

Since AgentPost is self-hosted, these are configurable defaults. You can adjust them in your deployment configuration.

Does AgentPost support API versioning?

The API is currently at v1 (/api/v1/...). When breaking changes are necessary, a new version will be introduced (e.g., /api/v2/...) with a migration guide and deprecation timeline. The current v1 API will remain supported for at least 12 months after v2 is released.

How do I authenticate API requests?

Include your API key in the Authorization header:

curl https://api.agent-post.dev/api/v1/inboxes \
  -H "Authorization: Bearer ap_sk_live_your_key_here"

For user-based authentication (web console), AgentPost uses JWT tokens with refresh token rotation.

Platform

Can I use AgentPost with Claude, GPT, or other LLMs?

Yes. AgentPost is designed to work with any AI model or framework:

• REST API -- Works with any language or framework that can make HTTP requests
• TypeScript SDK -- For Node.js-based AI agents
• Python SDK -- For Python-based AI agents (LangChain, CrewAI, AutoGen, etc.)
• MCP Server -- Direct integration with Claude, Cursor, Windsurf, and other MCP-compatible tools

How do environments work?

Environments provide resource isolation within an organization. Each environment has its own set of inboxes, domains, webhooks, and other resources. Common patterns:

• development / staging / production for deployment stages
• Per-customer environments for multi-tenant platforms
• Per-agent environments for multi-agent systems

See Environment Isolation for detailed guidance.

How do I report bugs?

Open an issue on the AgentPost GitHub repository. Include:

• Steps to reproduce the issue
• Expected behavior vs actual behavior
• AgentPost version and deployment details
• Relevant log output (with sensitive data redacted)

For security vulnerabilities, please email [email protected] instead of opening a public issue.

Is there a web console?

Yes. AgentPost includes a full web console for managing your organization, inboxes, messages, domains, webhooks, and team members. The console is built with React and TanStack Router and is served alongside the API.

Can I run multiple AgentPost instances?

Yes. AgentPost is stateless (aside from the database) and can be horizontally scaled behind a load balancer. All instances connect to the same PostgreSQL database. WebSocket connections require sticky sessions or a Redis-based adapter for multi-instance deployments.