sentio
Email inbox API for AI agents. Give every agent its own real email address, receive mail as structured webhooks, and reply in-thread over REST. A complete multi-tenant mail server in Rust: inbound and outbound, DKIM/SPF/DMARC/ARC, MTA-STS, DANE, three-tier anti-spam.
What is it?
What it is
Sentio is an SMTP server and email inbox API for AI agents, written in Rust. It provides each agent with its own real email address, receives mail as structured webhooks, and allows replies in-thread over REST. It supports multi-tenancy, full email protocol implementation (inbound and outbound), and includes DKIM/SPF/DMARC/ARC authentication, anti-spam scanning, and deliverability features.
Why it exists
AI agents increasingly need to participate in email conversations - receiving customer threads, acting on them, and replying as themselves. Traditionally this requires wiring together an IMAP poller, a parser, and an SMTP relay, inheriting a legacy MTA's operational complexity. Sentio consolidates this entire workflow into a single service, enabling agentic platforms to offer email capabilities without the operational overhead of legacy mail infrastructure.
Who should use it
AI agent platforms and SaaS providers embedding email capabilities, needing isolated per-tenant inboxes, webhook-delivered parsed mail, and DKIM-signed outbound. Suitable for developers building agentic systems who want full mail infrastructure without managing an MTA.
Who should avoid it
Those without PostgreSQL, Redis, NATS with JetStream, and S3-compatible storage infrastructure. Not for users seeking a hosted email API without operational overhead or those unprepared for mail server DNS, TLS, and protocol compliance requirements.
Stars over time
No change stars in the last 1 day
How it works
A quick walkthrough in plain English
How sentio works
Step 1 of 3
You interact with it
Open sentio, send a request, or connect it to your stack.
Features
Advantages
- Complete mail server rather than a wrapper around third-party APIs - full protocol control
- Multi-tenancy at every layer without shared state between customers
- Self-contained binary serves its own documentation and OpenAPI spec
- Rust provides memory safety and strong performance characteristics
- LLM integration enables AI-powered spam classification tiebreak for uncertain messages
- No compilation required - prebuilt Docker images for linux/amd64 and linux/arm64
- Automatic DKIM signing keeps outbound mail authenticated
- Compile-time SQL checking with sqlx without needing a live database to build
- Per-tenant dedicated or shared IP pools with configurable warmup schedules
- Forwarding rewrites From header and re-signs with tenant DKIM key, preserving deliverability
- Batch sending up to 500 messages in single API call
- Webhook payloads are metadata-only by default, keeping handlers fast regardless of attachment size
- Flexible configuration via TOML files with environment variable overrides
- Per-tenant Bayesian spam training on their own mail patterns
- Catch-all, domain, regex, and exact-match inbound routing options
- Comprehensive RFC compliance documentation and audits
Disadvantages
- Requires PostgreSQL 18+ specifically due to uuidv7() built-in function dependency
- Minimum 4GB RAM and 8GB disk for Docker deployment
- Complex dependency stack requiring 4+ external services (PostgreSQL, Redis, NATS, S3)
- Bootstrap API key has wildcard scope and must be rotated before production exposure
- Production mail requires DNS configuration: A, AAAA, MX, PTR, SPF, DKIM, DMARC records
- Port 25 outbound is blocked by default on AWS, GCP, Azure, Oracle, and Hetzner
- Requires understanding of email deliverability practices to avoid spam folder placement
- Port 465 (SMTPS) only binds when TLS certificates are present
- Requires ClamAV and rspamd running for full anti-spam coverage
- Manual DKIM key rotation and DNS record updates needed periodically
- Rust implementation limits customization for non-Rust developers
- Multiple configuration sections and options may overwhelm new users
- Requires setting capabilities or running as root to bind ports below 1024
- Systemd unit dependencies (postgresql.service, nats.service) must match actual service names
- Docker compose override syntax (!override) is non-standard YAML
- Background DNS checks must be run manually to verify published records after domain setup
Installation
compose
Rotate this key before exposing the host to anything untrusted - it has
wildcard (`*`) scope. Create a replacement via
`POST /v1/tenants/{id}/api-keys`, then delete the bootstrap one.
### Ports
| Port | Purpose | Notes |
|------|---------|-------|
| 25 | SMTP (MX) | Inbound mail from other servers |
| 465 | SMTPS | Implicit TLS - only binds when certificates are present |
| 587 | Submission | STARTTLS |
| 8080 | REST API | Also serves `/openapi.json` |
| 9001 | MinIO console | Optional; remove from compose to hide |
Already running something on port 25 (Postfix, Exim)? Either stop it or remap,
by creating a `docker-compose.override.yml`:FAQ
How can I run Sentio quickly using Docker?
Run `git clone https://github.com/truespar/sentio.git && cd sentio && docker compose up -d`. This starts Sentio with all required services (PostgreSQL, Redis, NATS, MinIO, etc.). The server is ready at `http://localhost:8080`. Use `docker compose logs -f sentio` to watch startup and `curl localhost:8080/health/ready` to verify health.
What are the minimum requirements to install Sentio without Docker?
You need Rust stable (edition 2021) plus build tools (`cmake`, `libclang-dev`, a C toolchain). A running PostgreSQL 18+ (for `uuidv7()`), Redis/Valkey, NATS with JetStream enabled, and an S3‑compatible storage (e.g., MinIO). Optional services like ClamAV and rspamd improve scanning but are not required. After installing dependencies, run `cargo build --release`, apply migrations, configure `sentio.toml`, and start the binary.
How do I send my first email using Sentio?
1. Register a sending domain via `POST /v1/domains` (set `use_for_sending`). 2. Create a DKIM key for the domain (`POST /v1/domains/{id}/dkim-keys`). 3. Fetch DNS records (`GET /v1/domains/{id}/dns-records`) and publish them (SPF, DKIM, DMARC). 4. Verify the domain with the token returned at registration (`POST /v1/domains/{id}/verify`). 5. Send the message with `POST /v1/messages/send`, providing `from`, `to`, `subject`, `text`/`html`, etc.
How does Sentio deliver inbound mail to agents and what does the webhook payload contain?
Create a receiving domain and an inbound route (match type, pattern, webhook URL). When mail arrives, Sentio authenticates (SPF/DKIM/DMARC), scans, scores, and fires a POST to your webhook. The payload includes `message_id`, `tenant_id`, `domain_id`, envelope addresses, `raw_eml_key`, `spam_score`, `spam_action`, and flags like `auto_submitted`. The original message and attachments are fetched separately via `GET /v1/messages/{id}/raw` and the attachments endpoints.
What is the sentio-mcp server and how do I use it?
The `sentio-mcp` binary is a Model Context Protocol server that exposes Sentio’s REST API as callable tools (list messages, send, reply, create mailbox, etc.). Download the pre‑built archive for your platform, set `SENTIO_BASE_URL` and `SENTIO_API_KEY` environment variables, and run it. Then add the server to your MCP client (e.g., Claude Desktop) and you can invoke email operations directly from the agent.
How can I scale Sentio for multiple customers (tenants)?
Create a tenant per customer (`POST /v1/tenants`), assign a tier (`dedicated` or `shared_*`), and generate an API key with `POST /v1/tenants/{id}/api-keys`. Each tenant gets isolated domains, mailboxes, DKIM keys, suppression lists, and reputation. Use inbound routes and webhooks per tenant, and control sending limits via tenant‑specific rate limits and IP pools.
Featured in Videos
YouTube tutorials and walkthroughs for sentio
Alternatives
Similar projects ranked by category, topics, and text overlap.
