Introduction

This page covers the architecture of AgentPost, introduces the core concepts you will work with, and explains how authentication works.

Architecture

AgentPost is a modular platform with several components working together:

                    +-------------------+
                    |   Your AI Agent   |
                    +-------------------+
                            |
            REST API / SDK / MCP / SMTP / IMAP
                            |
                    +-------------------+
                    |   Hono API Server |
                    +-------------------+
                     /      |       \
            +-------+  +-------+  +-------+
            | Postgres| |  SES  |  |  S3   |
            | (data)  | |(email)|  |(files)|
            +-------+  +-------+  +-------+
                |
            +-------+
            | pg-boss|
            | (jobs) |
            +-------+

API Server -- The Hono-based API server handles all REST requests, WebSocket connections, and webhook delivery orchestration. It is the central component.

PostgreSQL -- All data lives in PostgreSQL 16: organizations, inboxes, messages, threads, labels, domains, API keys, audit logs, and more.

AWS SES -- Simple Email Service handles outbound email sending and inbound email receiving. SES delivers inbound email to the API server via SNS notifications.

S3-compatible storage -- Cloudflare R2 (or any S3-compatible provider) stores email attachments and exports. Presigned URLs provide secure, time-limited access.

pg-boss -- A PostgreSQL-backed job queue handles background work: webhook delivery, domain verification polling, bounce processing, and scheduled cleanup tasks.

SMTP/IMAP servers -- Optional protocol servers provide standard email client access. Agents or humans can connect with Thunderbird, Apple Mail, or any standard email client.

Core concepts

AgentPost organizes resources in a hierarchy:

Organization
  |-- Environments (tenant isolation)
  |-- Inboxes (email addresses)
  |     |-- Messages (individual emails)
  |     |-- Threads (conversation groupings)
  |     |-- Drafts (unsent messages)
  |-- Domains (custom sending domains)
  |-- Webhook Endpoints (event delivery)
  |-- API Keys (authentication)
  |-- Members (team access)

Organizations

An organization is the top-level container. All resources belong to an organization. Each organization has:

• A name and slug identifier
• A tier (free, starter, team, enterprise) that determines resource limits
• Members with roles (owner, admin, member)
• Governance policies and audit logging

Environments

Environments provide tenant isolation within an organization. A "default" environment is created automatically. Inboxes, messages, and domains are scoped to an environment, so you can separate production, staging, and per-customer data.

Inboxes

An inbox is an email address that can send and receive messages. Inboxes are created via the API and get an address like [email protected] on the shared domain, or [email protected] on a custom domain.

Messages

A message is a single email (sent or received). Messages have a direction (inbound or outbound), belong to an inbox, and are automatically grouped into threads.

Threads

A thread is a conversation -- a group of related messages linked by email headers (In-Reply-To, References). Threads are created automatically when messages are received or sent.

Labels

Labels are string tags you can attach to messages and threads. Use them for categorization, status tracking, or any custom classification your agent needs.

Domains

Custom domains let you send from your own addresses (like [email protected]). Domain setup involves DNS verification (SPF, DKIM, DMARC) and is managed through the API.

For detailed documentation on each concept, see the Core Concepts section.

Authentication

AgentPost uses API keys for authentication. Every API request must include a valid API key in the Authorization header.

API key format

API keys use the prefix ap_sk_ followed by a random string:

ap_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Authentication header

Include the API key as a Bearer token:

Authorization: Bearer ap_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Scopes

API keys have scopes that control what operations they can perform:

Create API keys with the minimum scopes your agent needs. You can always create additional keys with different scope combinations.

User authentication

The web console and some SDK features support JWT-based user authentication with email/password, OAuth (Google, GitHub), and SSO (OIDC, SAML). User authentication is separate from API key authentication and is typically used by human operators, not agents.

Base URL

All API endpoints are available at:

https://api.agent-post.dev/api/v1/

If you are self-hosting, replace this with your own API server URL.

Next steps

Ready to start building? Head to the Quickstart to create your first inbox and send an email.