Overview
What pigeon is, how it is built and what it can do.
pigeon sends transactional email on behalf of your applications. A site calls the API with a template and its data, pigeon delivers through the SMTP server configured for that project and records the outcome. Around it there is a panel to write the templates, configure the projects and see what went out.
What it solves is fragmentation: without it every application carries its own SMTP credentials, its own HTML pasted into the code and no history at all. With pigeon the credentials live in one place and encrypted, the templates change without touching the code, and every send leaves a row behind.
pigeon is not a mail service and has no delivery servers of its own: it sends through the SMTP server you give it, project by project.
The four objects
Project: a container with its own SMTP settings. It decides the sender, which never depends on the user sending. It usually maps to one application or one customer.
Template: HTML with {{field}} placeholders, replaced at send time. Templates belong to
the user and not to the project, so the same template can go out from different projects.
API key: the credential an application sends with. It belongs to the project, so the project is implicit in the key and is not passed in the request.
Send: a row in the history with recipients, subject, outcome and id. It is created before pigeon contacts the SMTP server, so it exists even when something goes wrong halfway.
What it can do
- Sending from a template with data substituted at runtime, one or fifty recipients at a time
- Attachments, up to five files of 5 MB each, on the same route in
multipart/form-data - Independent projects, each with its own SMTP server and its own sender
- API keys per project, revocable, shown once and kept as a hash
- Encrypted SMTP passwords in the database, never returned by any route
- Send history with outcome, error and template used, paginated by cursor
- Application logs filtered per user, with no secrets in the metadata
- Statistics by status, over time and by template usage, per project
- Rate limiting per key, so a runaway loop does not burn the reputation of the domain
- Liveness and readiness probes for external monitoring
- OpenAPI documentation generated from the route schemas, always in step with the code
Where to start
If you have to configure the service, start from Getting started. If you have to write the code that calls it, go to Sending and then to Reliability, which is the page that keeps mail from getting lost.