Usage

Configuration

The service loads settings from config.ini (or the path provided by ASYNC_MAIL_CONFIG) and environment variables. Main sections/keys:

[storage]     db_path
[server]      host, port, api_token
[client]      client_sync_url, client_sync_user, client_sync_password, client_sync_token
[scheduler]   active, timezone
[delivery]    send_interval_seconds, test_mode, default_priority, delivery_report_retention_seconds
[logging]     delivery_activity

api_token secures the FastAPI endpoints: every HTTP request must include X-API-Token: <value>. The [client] section configures the outbound proxy_sync call performed by the dispatcher towards the Genropy server. Credentials are sent using HTTP basic authentication (the same format obtained with https://user:password@host/path URLs) unless client_sync_token is provided.

Enable [logging] delivery_activity = true to surface each SMTP attempt and every client sync exchange directly in the console logs, useful during troubleshooting or integration debugging.

Proxy sync exchange

When the scheduler has delivery results to report, it POSTs to proxy_sync_url with basic auth:

{
  "delivery_report": [
    {"id": "MSG-001", "account_id": "accA", "priority": 1, "sent_ts": 1728460800, "error_ts": null, "error": null, "deferred_ts": null},
    {"id": "MSG-002", "account_id": "accA", "priority": 2, "sent_ts": null, "error_ts": 1728461112, "error": "SMTP timeout", "deferred_ts": null}
  ]
}

If no events are pending, delivery_report is an empty list. A typical response from Genropy is:

{"sent": 12, "error": 1, "deferred": 0}

Genropy will subsequently push new messages through /commands/add-messages. For automated deployments the background SMTP and reporting loops poll the queue every send_interval_seconds. The /commands/run-now shortcut can be used to force an immediate iteration, waking the loops without waiting for the scheduled interval.

Endpoints

GET /status
POST /commands/run-now
POST /commands/suspend
POST /commands/activate
POST /commands/add-messages
POST /account
GET /accounts
DELETE /account/{id}
GET /messages
GET /metrics

Test mode

Unit tests and maintenance scripts can instantiate async_mail_service.core.AsyncMailCore (or set [delivery] test_mode = true in config.ini) with test_mode=True. In this mode the dispatcher and reporting tasks are still created, but their send interval is stretched to infinity so they wait for an explicit wake-up. Calling /commands/run-now (or handle_command("run now", {})) raises that wake-up, making the loops process the next cycle immediately while still exercising the same code paths used in production. Production services should leave test_mode at its default False value so the periodic loops continue to process the queue automatically without manual intervention.

REST Examples (curl)

Add account:

curl -X POST http://localhost:8000/account \
     -H "Content-Type: application/json" \
     -H "X-API-Token: my-secret-token" \
  -d '{
  "id":"gmail","host":"smtp.gmail.com","port":587,
  "user":"you@gmail.com","password":"***","use_tls":false,
  "limit_per_minute":30,"limit_per_hour":500,"limit_per_day":1000
}'

Python (httpx)

import httpx

client = httpx.Client(base_url="http://localhost:8000",
                      headers={"X-API-Token": "my-secret-token"})

r = client.post("/commands/add-messages", json={
    "messages": [
        {
            "id": "MSG-001",
            "from": "sender@example.com",
            "to": ["dest@example.com"],
            "subject": "Hi",
            "body": "Hello world"
        }
    ]
})
print(r.json())