API Reference

FastAPI

The REST API is served by FastAPI. The automatically generated documentation is available at:

OpenAPI JSON: http://localhost:8000/openapi.json
Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

All endpoints require the X-API-Token header when [server] api_token (or API_TOKEN) is configured.

Core endpoints

POST /commands/run-now: Wake the dispatcher and reporting loops so they execute a cycle immediately instead of waiting for the next scheduled interval. Useful for maintenance scripts and for test_mode instances where the interval is effectively infinite.
POST /commands/suspend / POST /commands/activate: Toggle the scheduler.
POST /commands/add-messages: Validate and enqueue a batch of messages. Each payload entry matches async_mail_service.api.MessagePayload; the response contains the number of queued items plus a rejected list with {"id","reason"} entries describing invalid payloads (missing id, bad addresses, unknown account, duplicates, …).
POST /account / GET /accounts / DELETE /account/{id}: Manage SMTP account credentials.
GET /messages: Inspect the SQLite-backed messages table. Each record includes the payload plus lifecycle fields (priority, deferred_ts, sent_ts, error_ts, error, reported_ts).
GET /metrics: Expose Prometheus metrics generated by async_mail_service.prometheus.MailMetrics.

Prometheus metrics

The following metrics are exported:

asyncmail_sent_total{account_id}
asyncmail_errors_total{account_id}
asyncmail_deferred_total{account_id}
asyncmail_rate_limited_total{account_id}
asyncmail_pending_messages

Outbound proxy sync

Besides REST endpoints that clients call, the service also issues a POST request to the configured proxy_sync_url whenever there are delivery results to share with Genropy. Example payload:

The payload contains the delivery results read from the messages table:

{
  "delivery_report": [
    {
      "id": "MSG-101",
      "account_id": "accA",
      "priority": 1,
      "sent_ts": 1728458400,
      "error_ts": null,
      "error": null,
      "deferred_ts": null
    },
    {
      "id": "MSG-102",
      "account_id": "accA",
      "priority": 2,
      "sent_ts": null,
      "error_ts": 1728458612,
      "error": "SMTP timeout",
      "deferred_ts": null
    }
  ]
}

The proxy replies with a JSON summary (for example {"sent": 12, "error": 1, "deferred": 3}). Upon success the dispatcher sets reported_ts on the transmitted rows and cleans up any message whose reported_ts is older than the configured retention window.