Cloady Docs
API ReferenceEndpointsApplications

Read a mail service's delivery

Reads a Postfix service's delivery log and queue: outbound attempts by outcome per step, time to delivery, inbound rejections and authentication failures, outcomes by recipient domain, bounce reasons with addresses masked, the queue's size by state and the retry settings. Postfix must log to standard output (`maillog_file = /dev/stdout`). Stalwart is read from its own Prometheus exporter and JMAP API once its admin turns the exporter on and the app holds an API key as the variable STALWART_API_KEY (and the exporter's login, if it has one, as STALWART_METRICS_AUTH, written user:secret); Mailpit and MailHog report what they caught. Nothing is invented for a server Monitor cannot read.

GET
/api/workspaces/{workspaceSlug}/apps/{appSlug}/services/{serviceName}/mail

Authorization

cloady
AuthorizationBearer <token>

Personal API token (cldy_…)

In: header

Path Parameters

workspaceSlug*string
appSlug*string
serviceName*string

Query Parameters

env?string

Value in

  • "production"
  • "preview"
  • "development"
region?string
range?string

How far back to look; the answer has 30 to 96 points across it

Default"1h"

Value in

  • "15m"
  • "1h"
  • "6h"
  • "24h"
  • "7d"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/apps/string/services/string/mail"
{  "at": 0,  "start": 0,  "step": 0,  "engine": "postfix",  "logs": true,  "series": {    "sent": [      0    ],    "deferred": [      0    ],    "bounced": [      0    ],    "rejected": [      0    ],    "p50": [      0    ],    "p95": [      0    ]  },  "totals": {    "sent": 0,    "deferred": 0,    "bounced": 0,    "expired": 0,    "rejected": 0,    "authFailures": 0  },  "providers": [    {      "domain": "string",      "attempts": 0,      "sent": 0,      "deferred": 0,      "bounced": 0,      "topDeferral": "string",      "median": 0    }  ],  "bounces": [    {      "kind": "hard",      "dsn": "string",      "reason": "string",      "count": 0    }  ],  "bouncesSampled": true,  "queue": {    "active": 0,    "deferred": 0,    "hold": 0,    "incoming": 0,    "total": 0,    "partial": true  },  "captured": {    "total": 0,    "series": [      0    ],    "sampled": true  },  "stalwart": {    "metrics": "read",    "api": "read",    "counters": {      "delivered": 0,      "deferred": 0,      "bounced": 0,      "rejected": 0,      "authFailures": 0,      "dmarcPass": 0,      "dmarcFail": 0    },    "queued": 0  },  "backoff": {    "minimal": "string",    "maximal": "string",    "lifetime": "string"  },  "notes": [    "string"  ],  "queries": [    {      "lang": "LogQL",      "text": "string"    }  ]}

Retry failed BullMQ jobs POST

Moves one failed job, or every failed job of a BullMQ queue, back to the queue's waiting list through the bullmq library, so the app's workers run it again. BullMQ 5 or later only; Sidekiq, Celery and RabbitMQ have no retry here. Requires the developer role.

List a mail service's queued messages GET

Lists up to 100 messages in a Postfix queue, or in Stalwart's through its API, with their sender, recipients, the remote server's last reply, when the server tries again and how many attempts it has made. Requires the developer role, because it shows addresses.