No description
  • Go 88.9%
  • Shell 8.9%
  • Dockerfile 2.2%
Find a file
Jonas Leder c0f751d214
All checks were successful
ci / build (push) Successful in 2m51s
ci / docker (push) Successful in 0s
CI: port GitLab pipeline to Forgejo Actions
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-18 10:48:36 +01:00
.forgejo/workflows CI: port GitLab pipeline to Forgejo Actions 2026-11-18 10:48:36 +01:00
internal add jmap support 2026-10-28 13:41:18 +01:00
scripts add jmap support 2026-10-28 13:41:18 +01:00
.dockerignore rebuild in golang 2026-10-28 13:05:43 +01:00
.env.example add jmap support 2026-10-28 13:41:18 +01:00
.gitignore rebuild in golang 2026-10-28 13:05:43 +01:00
docker-compose.yml add jmap support 2026-10-28 13:41:18 +01:00
Dockerfile rebuild dockerfile 2026-10-28 13:08:34 +01:00
go.mod add jmap support 2026-10-28 13:41:18 +01:00
go.sum add jmap support 2026-10-28 13:41:18 +01:00
main.go add jmap support 2026-10-28 13:41:18 +01:00
README.md add jmap support 2026-10-28 13:41:18 +01:00

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's catchAllAddress to the catch-all account catchall@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

  1. Copy the environment template and fill in the values:

    cp .env.example .env
    

    STALWART_RECOVERY_ADMIN is the password of the temporary recovery admin. Pick any value.

  2. Start Stalwart:

    docker compose up -d stalwart
    
  3. 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.sh
    

    The script prints the admin login of the new server. Save it, the password is shown only once. Use the same CATCHALL_PASSWORD as JMAP_PASSWORD in .env.

  4. Remove STALWART_RECOVERY_ADMIN from .env, then start the API:

    docker compose up -d
    
  5. Publish the DNS records for the domain (MX, SPF, DKIM, DMARC). Stalwart prints them with View Zone File in 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 To and Cc headers. 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 in Bcc is discarded.
  • Expired aliases stop working after the next sweep, at most SWEEP_INTERVAL later.
  • 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.