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
   :class:`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
   :class:`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:

.. code-block:: json

   {
     "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.