Mail Transport Failed

mail-transport-failed · 503

The mail server refused the test email, so nothing was sent.

Only the test email answers with this: an alert that fails to send is dropped quietly. The minute the test claimed is given back, so the next try isn't throttled.

This type adds no members to the ones every error carries.

Common causes

  • The mail server was down, slow or refused the message at that moment.

How to fix the call

  • Retry after a short wait.
  • If it keeps failing, tell the user email alerts may not arrive either, quoting detail.

Example response

json
{
  "type": "mail-transport-failed",
  "title": "Mail Transport Failed",
  "detail": "The mail server refused the test message. Nothing was sent; try again shortly.",
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/notifications/test",
  "method": "POST",
  "instance": "POST /v1/notifications/test",
  "status": 503,
  "docs": "https://ghaym.me/docs/errors/mail-transport-failed"
}