How to monitor the size of the "Held" message queue?

[zdeneksvarc]

Hello,

I’m setting up Prometheus and Grafana monitoring for Postal and need to monitor how many messages are currently in the “Held” state.

Current situation

• /metrics on ports 9090 and 9091 provide worker and SMTP statistics.
• The ExpireHeldMessagesScheduledTask metric shows cleanup runs, but not how many messages are held.
• There’s no API parameter like ?state=Held in /api/v1/messages (checked in the official API docs).
• The /org/.../messages/held admin page lists held messages, but it’s not an API endpoint.

Why this matters

Monitoring the size of the held queue is important for:

• detecting spam or policy-related message backlogs,
• ensuring the cleanup job is running correctly,
• alerting if held messages remain for too long.

Suggested improvements

1. Expose a Prometheus metric, for example:
   postal_messages_held_total
   showing Message.where(status: 'Held').count.

2. Add an API filter parameter, e.g.:
   /api/v1/messages?state=Held

Current workaround

• Scrape the admin page /messages/held, or
• Query the database directly:
  SELECT COUNT(*) FROM messages WHERE status = 'Held';

Would you consider adding or documenting a supported way to retrieve the current “Held” queue size for monitoring purposes?

[willpower232]

I'm sure a PR would be welcomed, I can't move this to Feature Suggestions because github is a delight

You could source the information yourself from the database but not as cleanly as the way you're suggesting.