SMTP Credentials¶

Domain-scoped SMTP API keys, distinct from mailbox passwords. A credential authenticates only over SMTP (ports 587/465, via a protocol-scoped Dovecot passdb) and may send as any address at its domain. This module went live in production on 2026-08-27.

The API server is the single source of truth for the whole lifecycle: secrets are generated server-side, returned exactly once in the create/rotate response, and stored only as a bcrypt hash plus a short display prefix. active, expires_at, and allowed_ips are enforced inside the Dovecot passdb query; every auth-affecting mutation additionally flushes Dovecot's auth cache for the username, so a revoked key stops authenticating on the next AUTH attempt instead of after the 1-hour cache TTL.

Mailbox-password SMTP auth is untouched — the credentials table is additive.

Base path: /api/v1/smtp-credentials Auth: X-API-Key (read for GETs, write for mutations) or a dashboard session. Tenant credentials are scoped to their own organization; platform-scope credentials see every organization.

Routes are split across two modules that share the same prefix: routes/smtp_credentials.py (lifecycle) and routes/smtp_credential_reports.py (events + usage reads).

The credential object¶

All lifecycle endpoints return this shape in data:

The plaintext secret appears only in create (when generated) and rotate responses. It is never retrievable again.

List SMTP Credentials¶

GET /api/v1/smtp-credentials

Query Parameters

Example Request

curl -H "X-API-Key: YOUR_KEY" \
  "http://your-server:5000/api/v1/smtp-credentials?domain_id=01J8ZK...&limit=50"

Example Response

{
  "type": "success",
  "msg": "SMTP credentials retrieved successfully",
  "data": {
    "credentials": [
      {
        "id": "01J9AB2CD3EF4GH5JK6MN7PQ8R",
        "organization_id": "01J8ZJXQ2W3E4R5T6Y7U8I9O0P",
        "domain_id": "01J8ZK1A2B3C4D5E6F7G8H9J0K",
        "username": "smtp-acme-com-x7k2",
        "name": "Marketing sender",
        "prefix": "mk_7f3a2b",
        "created_by": "admin@acme.com",
        "allowed_ips": ["203.0.113.0/24"],
        "ip_allowlist_enabled": true,
        "expires_at": null,
        "hourly_limit": 500,
        "daily_limit": 5000,
        "last_used_at": "2026-08-29T14:03:22",
        "active": true,
        "created_at": "2026-08-27T09:15:00",
        "updated_at": "2026-08-29T14:03:22"
      }
    ],
    "total": 1
  }
}

Create SMTP Credential¶

Provision a domain-scoped SMTP API key. When username/password are omitted the server generates them and the response carries the plaintext secret exactly once.

POST /api/v1/smtp-credentials

Request Body

Example Request

curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "01J8ZK1A2B3C4D5E6F7G8H9J0K",
    "name": "Marketing sender",
    "allowed_ips": ["203.0.113.0/24"],
    "ip_allowlist_enabled": true,
    "hourly_limit": 500,
    "daily_limit": 5000
  }' \
  http://your-server:5000/api/v1/smtp-credentials

Example Response (201 Created)

{
  "type": "success",
  "msg": "SMTP credential created successfully",
  "data": {
    "id": "01J9AB2CD3EF4GH5JK6MN7PQ8R",
    "username": "smtp-acme-com-x7k2",
    "prefix": "mk_7f3a2b",
    "secret": "mk_7f3a2b9c1d4e...",
    "active": true,
    "...": "full credential object"
  }
}

Get SMTP Credential¶

GET /api/v1/smtp-credentials/{credential_id}

Example Request

curl -H "X-API-Key: YOUR_KEY" \
  http://your-server:5000/api/v1/smtp-credentials/01J9AB2CD3EF4GH5JK6MN7PQ8R

Returns the credential object (no secret). 404 if the ID does not exist or belongs to another organization.

Update SMTP Credential¶

Partial update — only the keys present in the request body are applied.

PATCH /api/v1/smtp-credentials/{credential_id}

Request Body (all fields optional; at least one required)

Example Request

curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_at": "2026-12-31T23:59:59", "daily_limit": 10000}' \
  http://your-server:5000/api/v1/smtp-credentials/01J9AB2CD3EF4GH5JK6MN7PQ8R

Example Response

{
  "type": "success",
  "msg": "SMTP credential updated successfully",
  "data": {
    "...": "full credential object",
    "cache_flushed": true
  }
}

422 if no updatable field is provided, or on allowlist/expiry validation failure. When allowed_ips, ip_allowlist_enabled, or expires_at change, the response includes cache_flushed — whether Dovecot's auth cache was flushed for the username (those values are read at AUTH time from the passdb query).

Rotate SMTP Credential¶

Generates a new secret for the same username, so SMTP clients only change their password. The response carries the new plaintext exactly once.

POST /api/v1/smtp-credentials/{credential_id}/rotate

Example Request

curl -X POST -H "X-API-Key: YOUR_KEY" \
  http://your-server:5000/api/v1/smtp-credentials/01J9AB2CD3EF4GH5JK6MN7PQ8R/rotate

Example Response

{
  "type": "success",
  "msg": "SMTP credential rotated successfully",
  "data": {
    "...": "full credential object",
    "secret": "mk_9e2c1a8b...",
    "cache_flushed": true
  }
}

The old secret stops working on the next AUTH attempt (cache flushed after commit), not after the 1-hour auth-cache TTL.

Revoke SMTP Credential¶

Sets active: false and flushes Dovecot's auth cache for the username, so the key stops authenticating on the next AUTH attempt — no auth-cache window. Idempotent.

POST /api/v1/smtp-credentials/{credential_id}/revoke

Example Request

curl -X POST -H "X-API-Key: YOUR_KEY" \
  http://your-server:5000/api/v1/smtp-credentials/01J9AB2CD3EF4GH5JK6MN7PQ8R/revoke

Example Response

{
  "type": "success",
  "msg": "SMTP credential revoked",
  "data": {
    "...": "full credential object (active: false)",
    "cache_flushed": true
  }
}

Re-enable SMTP Credential¶

Undo a revocation.

POST /api/v1/smtp-credentials/{credential_id}/enable

curl -X POST -H "X-API-Key: YOUR_KEY" \
  http://your-server:5000/api/v1/smtp-credentials/01J9AB2CD3EF4GH5JK6MN7PQ8R/enable

Same response shape as revoke, with msg: "SMTP credential enabled".

Delete SMTP Credential¶

Permanently delete a credential. Idempotent — deleting an already-absent credential also returns success, matching the mailbox/domain delete convention. An audit event row is written first and survives the delete.

DELETE /api/v1/smtp-credentials/{credential_id}

Example Request

curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  http://your-server:5000/api/v1/smtp-credentials/01J9AB2CD3EF4GH5JK6MN7PQ8R

Example Response

{
  "type": "success",
  "msg": "SMTP credential deleted successfully",
  "data": { "cache_flushed": true }
}

Credential Events (Audit Trail)¶

Append-only key events (created, updated, rotated, revoked, enabled, deleted, suspended), newest first. Event rows are FK-free — they survive the deletion of the credential and organization they describe.

GET /api/v1/smtp-credentials/{credential_id}/events

Query Parameters

Example Request

curl -H "X-API-Key: YOUR_KEY" \
  "http://your-server:5000/api/v1/smtp-credentials/01J9AB2CD3EF4GH5JK6MN7PQ8R/events?limit=20"

Example Response

{
  "type": "success",
  "msg": "SMTP credential events retrieved successfully",
  "data": {
    "events": [
      {
        "id": "01J9AC3DE4FG5HJ6KL7MN8PQ9S",
        "credential_id": "01J9AB2CD3EF4GH5JK6MN7PQ8R",
        "organization_id": "01J8ZJXQ2W3E4R5T6Y7U8I9O0P",
        "username": "smtp-acme-com-x7k2",
        "event": "rotated",
        "actor": "admin@acme.com",
        "source_ip": "198.51.100.7",
        "detail": null,
        "created_at": "2026-08-29T10:12:45"
      }
    ]
  }
}

Credential Usage (Delivery Counts)¶

Messages attributed to this key via mail_logs.sasl_username (populated by the log ingestor from smtpd's client= lines).

GET /api/v1/smtp-credentials/{credential_id}/usage

Query Parameters

Example Request

curl -H "X-API-Key: YOUR_KEY" \
  "http://your-server:5000/api/v1/smtp-credentials/01J9AB2CD3EF4GH5JK6MN7PQ8R/usage?days=7"

Example Response

{
  "type": "success",
  "msg": "SMTP credential usage retrieved successfully",
  "data": {
    "window_days": 7,
    "since": "2026-08-23T00:00:00",
    "total": 1240,
    "delivered": 1198,
    "bounced": 12,
    "deferred": 25,
    "rejected": 5,
    "by_status": { "delivered": 1198, "bounced": 12, "deferred": 25, "rejected": 5 },
    "last_used_at": "2026-08-29T14:03:22"
  }
}