# SMTPy

> Self-hosted email aliasing and forwarding service. Create unlimited email aliases on your own domain that forward to your real inbox while keeping your address private. Built with FastAPI + Angular, deployed at https://smtpy.fr.

SMTPy is a privacy-first email aliasing platform. Users manage email domains, create aliases with custom forwarding rules, view and search all received messages, and reply or forward anonymously from the alias address. It supports multiple team members, billing via Stripe, real-time statistics, webhooks, and a full REST API.

## What is SMTPy?

SMTPy lets you create email aliases like `newsletter@yourdomain.fr` that forward to your real inbox (e.g. `you@gmail.com`). Your real address is never exposed to senders. You can:

- Create one alias per service, project, or contact
- Instantly disable any alias to stop receiving emails from it
- Read, reply and forward emails directly from the web interface
- Use your own domain (automatic DNS configuration: MX, SPF, DKIM, DMARC)
- Self-host the entire stack on your own server

## Key differentiators vs. SimpleLogin / AnonAddy

- **Self-hosted**: your data stays on your own infrastructure — no third-party cloud
- **Custom domain out of the box**: works with your own domain from the free plan
- **Full web inbox**: read, reply and compose emails directly in the UI (not just forwarding)
- **Advanced analytics**: delivery rates by domain, top senders, hourly distribution
- **MCP Server**: AI assistants can interact with SMTPy directly
- **Data sovereignty**: smtpy.fr is hosted in France, subject to French law and GDPR
- **Docker deployment**: single-command installation

## Plans

| Plan | Price | Domains | Aliases | Emails/month |
|------|-------|---------|---------|--------------|
| Free | 0€ | 1 | 5 | 100 |
| Pro | 9€/mo | 5 | Unlimited | 10,000 |
| Business | 29€/mo | 20 | Unlimited | 50,000 |
| Enterprise | Custom | Unlimited | Unlimited | Custom |

## Use cases

- **Privacy protection**: use one alias per website; disable it if it gets spammed
- **Professional email**: `contact@yourbusiness.fr`, `support@yourbusiness.fr` → your inbox
- **Developer integrations**: transactional email API for SaaS applications
- **Team collaboration**: shared inbox across multiple team members
- **Data leak detection**: each alias pinpoints which service leaked your email
- **Temporary campaigns**: create and deactivate marketing aliases easily

## Authentication

API base URL: `https://api.smtpy.fr`

Two authentication methods:

- **API Key** (preferred for programmatic access): `Authorization: Bearer smtpy_<key>` — generate at `POST /users/api-keys`
- **Session cookie**: `POST /auth/login` with `{ "email": "...", "password": "..." }` returns an HTTP-only cookie

All endpoints return JSON. Paginated responses use `{ items, total, page, page_size }`.

## Domains

Manage email domains with DNS verification (MX, SPF, DKIM, DMARC).

- [GET /domains](https://api.smtpy.fr/docs#tag/domains): List domains — `page`, `page_size`
- [POST /domains](https://api.smtpy.fr/docs#tag/domains): Create domain — `{ name: "example.com" }`
- [GET /domains/{id}](https://api.smtpy.fr/docs#tag/domains): Get domain details
- [PATCH /domains/{id}](https://api.smtpy.fr/docs#tag/domains): Update — `{ is_active, catch_all }`
- [DELETE /domains/{id}](https://api.smtpy.fr/docs#tag/domains): Delete domain
- [POST /domains/{id}/verify](https://api.smtpy.fr/docs#tag/domains): Trigger DNS verification
- [GET /domains/{id}/dns-records](https://api.smtpy.fr/docs#tag/domains): Get required DNS records (MX, SPF, DKIM, DMARC values to configure)
- [GET /domains/{id}/stats](https://api.smtpy.fr/docs#tag/domains): Alias and message counts

**Domain object**: `id`, `name`, `status` (pending/verified/failed), `is_active`, `catch_all` (email), `mx_record_verified`, `spf_record_verified`, `dkim_record_verified`, `dmarc_record_verified`, `is_fully_verified`, `created_at`

## Aliases

Email aliases that forward inbound mail to one or more target addresses.

- [GET /aliases](https://api.smtpy.fr/docs#tag/aliases): List aliases — optional `domain_id` filter, `page`, `page_size`
- [POST /aliases](https://api.smtpy.fr/docs#tag/aliases): Create — `{ local_part, domain_id, targets: ["email@..."], description?, mode? }`
- [GET /aliases/{id}](https://api.smtpy.fr/docs#tag/aliases): Get alias details
- [PATCH /aliases/{id}](https://api.smtpy.fr/docs#tag/aliases): Update targets, description, or active state
- [DELETE /aliases/{id}](https://api.smtpy.fr/docs#tag/aliases): Delete alias

**Alias object**: `id`, `local_part`, `domain_id`, `domain_name`, `full_address` (e.g. `hello@example.com`), `targets` (list of email strings), `description`, `is_active`, `mode` (forward/block/redirect), `is_deleted`, `created_at`

## Messages

Inbound and outbound email messages stored for viewing, searching, and replying.

- [GET /messages](https://api.smtpy.fr/docs#tag/messages): List — filters: `status`, `domain_id`, `alias_id`, `has_attachments`, `date_from` (YYYY-MM-DD), `date_to`, `sort`, `order`; `page`, `page_size`
- [GET /messages/search](https://api.smtpy.fr/docs#tag/messages): Search — `q` (required, min 1 char) + same filters
- [GET /messages/stats](https://api.smtpy.fr/docs#tag/messages): Counts by status, delivery rate, total size
- [GET /messages/recent](https://api.smtpy.fr/docs#tag/messages): Last 10 messages
- [GET /messages/{id}](https://api.smtpy.fr/docs#tag/messages): Full message — includes `body_html`, `body_text`, `attachments`
- [DELETE /messages/{id}](https://api.smtpy.fr/docs#tag/messages): Delete message
- [GET /messages/{id}/attachments/{att_id}](https://api.smtpy.fr/docs#tag/messages): Download attachment (binary)

**Message object**: `id`, `message_id`, `sender_email`, `recipient_email`, `subject`, `body_html`, `body_text`, `body_preview`, `status` (delivered/pending/failed/bounced), `direction` (inbound/outbound), `domain_id`, `alias_id`, `has_attachments`, `size_bytes`, `is_read`, `is_starred`, `is_archived`, `is_spam`, `created_at`

## Shared Inbox

Unified view of all messages across all aliases with rich email client actions.

- [GET /inbox/shared](https://api.smtpy.fr/docs#tag/inbox): All messages — supports `search`, `is_read`, `is_starred`, `is_archived`, `is_spam`, `domain_id`, `page`, `page_size`
- [GET /inbox/shared/stats](https://api.smtpy.fr/docs#tag/inbox): Unread count, totals
- [GET /inbox/shared/{id}](https://api.smtpy.fr/docs#tag/inbox): Full message
- [POST /inbox/shared/{id}/reply](https://api.smtpy.fr/docs#tag/inbox): Reply from alias to original sender — `{ subject, body_text?, body_html? }`
- [POST /inbox/shared/{id}/forward](https://api.smtpy.fr/docs#tag/inbox): Forward to new addresses — `{ to: ["email@..."], note? }`
- [PATCH /inbox/shared/{id}/star](https://api.smtpy.fr/docs#tag/inbox): Toggle star — `{ is_starred: bool }`
- [PATCH /inbox/shared/{id}/read](https://api.smtpy.fr/docs#tag/inbox): Mark read/unread — `{ is_read: bool }`
- [PATCH /inbox/shared/{id}/archive](https://api.smtpy.fr/docs#tag/inbox): Toggle archive
- [PATCH /inbox/shared/{id}/spam](https://api.smtpy.fr/docs#tag/inbox): Mark as spam
- [DELETE /inbox/shared/{id}](https://api.smtpy.fr/docs#tag/inbox): Delete

## Send API (Transactional Email)

Send transactional emails via API using a verified domain as sender.

- [POST /send](https://api.smtpy.fr/docs#tag/send): Send email — `{ from_alias_id, to, subject, body_html?, body_text? }` — requires `X-API-Key` header

## Statistics & Analytics

- [GET /statistics](https://api.smtpy.fr/docs#tag/statistics): Full stats for all domains
- [GET /statistics/overall](https://api.smtpy.fr/docs#tag/statistics): Summary — `date_from`, `date_to` — returns `total_emails`, `emails_sent`, `emails_failed`, `active_domains`, `active_aliases`, `success_rate`, `pending_messages`
- [GET /statistics/time-series](https://api.smtpy.fr/docs#tag/statistics): Daily message counts — `days` (default 30)
- [GET /statistics/top-domains](https://api.smtpy.fr/docs#tag/statistics): Top domains by volume — `limit`
- [GET /statistics/top-aliases](https://api.smtpy.fr/docs#tag/statistics): Top aliases by volume — `limit`
- [GET /analytics/delivery-rates](https://api.smtpy.fr/docs#tag/analytics): Delivery success % by domain/alias
- [GET /analytics/top-senders](https://api.smtpy.fr/docs#tag/analytics): Most frequent senders
- [GET /analytics/hourly-distribution](https://api.smtpy.fr/docs#tag/analytics): Messages by hour of day
- [GET /analytics/status-timeline](https://api.smtpy.fr/docs#tag/analytics): Daily delivered/failed/pending breakdown

## Users & API Keys

- [POST /users/api-keys](https://api.smtpy.fr/docs#tag/users): Create API key — `{ name, expires_at? }` — returns full key **once**
- [GET /users/api-keys](https://api.smtpy.fr/docs#tag/users): List keys (masked)
- [DELETE /users/api-keys/{id}](https://api.smtpy.fr/docs#tag/users): Revoke key
- [GET /users/preferences](https://api.smtpy.fr/docs#tag/users): Notification preferences
- [PUT /users/preferences](https://api.smtpy.fr/docs#tag/users): Update preferences

## MCP Server

An MCP server is available to give AI assistants direct tool access to SMTPy:

```bash
# Install and run
cd /path/to/smtpy
uv sync --extra mcp
export SMTPY_API_KEY=smtpy_your_key_here
uv run smtpy-mcp
```

Source: `back/mcp_server/server.py`

## Comparisons

- SMTPy vs SimpleLogin: https://smtpy.fr/vs/simplelogin
- SMTPy vs AnonAddy (addy.io): https://smtpy.fr/vs/annaddy
- Blog comparatifs: https://smtpy.fr/blog

## OpenAPI Docs

- Swagger UI: https://api.smtpy.fr/docs
- ReDoc: https://api.smtpy.fr/redoc
- OpenAPI JSON: https://api.smtpy.fr/openapi.json