- Go 88.9%
- Shell 8.9%
- Dockerfile 2.2%
|
|
||
|---|---|---|
| .forgejo/workflows | ||
| internal | ||
| scripts | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| README.md | ||
email-alias-api
Creates time limited email aliases. A client posts a target address and an expiry date, the API returns a generated alias address. Mail sent to the alias is redirected to the target until the expiry date, after that it is discarded.
Mail is handled by Stalwart. The aliases are sieve rules in the active script of a catch-all account. The API manages that script over JMAP.
Architecture
-
Stalwart receives all mail for
MAIL_DOMAIN. Unknown recipients are routed by the domain'scatchAllAddressto the catch-all accountcatchall@MAIL_DOMAIN. -
The active sieve script of the catch-all account contains one block per alias:
# BEGIN alias bepojanuki@example.com expire=2031-05-06T10:00:00Z to=me@example.org if address :is ["to", "cc"] "bepojanuki@example.com" { redirect "me@example.org"; discard; stop; } # END alias bepojanuki@example.com discard;Creating an alias adds a block, the sweeper removes blocks whose expiry has passed. Mail that matches no block ends with
discard;and is not stored anywhere. -
The API keeps no database. The script is the only state.
Setup
-
Copy the environment template and fill in the values:
cp .env.example .envSTALWART_RECOVERY_ADMINis the password of the temporary recovery admin. Pick any value. -
Start Stalwart:
docker compose up -d stalwart -
Bootstrap Stalwart, create the catch-all account and route the domain to it:
STALWART_RECOVERY_ADMIN_PASSWORD=... \ MAIL_HOSTNAME=mail.example.com \ MAIL_DOMAIN=example.com \ CATCHALL_PASSWORD=... \ ./scripts/setup-stalwart.shThe script prints the admin login of the new server. Save it, the password is shown only once. Use the same
CATCHALL_PASSWORDasJMAP_PASSWORDin.env. -
Remove
STALWART_RECOVERY_ADMINfrom.env, then start the API:docker compose up -d -
Publish the DNS records for the domain (MX, SPF, DKIM, DMARC). Stalwart prints them with
View Zone Filein the admin UI under Management › Domains.
API
POST / with a JSON body:
{
"apikey": "change-me",
"targetMail": "me@example.org",
"expire": "2031-05-06T10:00:00Z"
}
expire accepts RFC 3339 and the local date-time formats 2006-01-02 15:04:05,
2006-01-02T15:04:05, 2006-01-02 15:04 and 2006-01-02. Naive values use the timezone of the
server.
Response:
{
"mailAddress": "bepojanuki@example.com",
"expire": "2031-05-06 10:00:00"
}
Errors are returned as {"error": "..."} with status 400 (invalid input or expiry in the past),
401 (wrong API key) or 500.
Configuration
See .env.example. The API reads its configuration from environment variables.
| Variable | Default | Purpose |
|---|---|---|
API_KEY |
required | key expected in apikey |
MAIL_DOMAIN |
required | domain for generated aliases |
JMAP_URL |
http://localhost:8080 |
base URL of Stalwart (compose sets http://stalwart:8080) |
JMAP_USERNAME |
required | catch-all account, e.g. catchall@example.com |
JMAP_PASSWORD |
required | password of the catch-all account |
SWEEP_INTERVAL |
1m |
how often expired rules are removed |
PORT |
8080 |
HTTP port of the API |
Known limitations
- Recipient matching uses the
ToandCcheaders. Stalwart 0.16 rewrites the envelope recipient to the catch-all address, so the original alias is not available in the envelope. Mail where the alias only appears inBccis discarded. - Expired aliases stop working after the next sweep, at most
SWEEP_INTERVALlater. - The sieve script is managed by the API. Manual edits outside the alias blocks are overwritten, and unknown marker lines make the API refuse to change the script.
- Redirected mail keeps the original sender. Receivers with strict DMARC policies may reject it.
- Stalwart is pinned to
v0.16.0, the behaviour above was tested with that version.