Troubleshoot Failed Notification Sending

This page helps you understand why a notification failed after it was created. Use this guide when you can see a notification in the communication log, but its status is Failed.

Scope

This page applies to email, SMS, and webhooks that appear in the communication log. It focuses on notifications that were created but could not be delivered to the recipient or provider.

note

Event Streaming uses a separate delivery pipeline and is not managed through the same communication log or resend flow.

Find failed notifications

To investigate failures, you must first locate the specific notification in the Communications tab (either at tenant level or on a specific client/account/group).

1. In the Mambu UI, open the Communications tab.
2. To see the technical details of the failure, customize your view:
   1. Click on Edit Columns.
   2. Check the Include timestamps checkbox.
   3. Add the following columns:
      • Creation Timestamp
      • Failure Reason – high-level error category.
      • Failure Details – short technical snippet (for example, HTTP status, provider error message, or exception text).
3. Locate the failed notification:
   1. Find the row where State is Failed.
   2. Click on it to open the full content.
   3. Review the payload, destination, and Failure Details to understand what went wrong.
4. If there are many notifications, apply filters to narrow down the search:
   1. Click the filter icon in the Communications tab.
   2. Create a filter based on criteria such as:
      • State = Failed
      • Channel (Email, SMS, Webhook)
      • Creation Timestamp range
      • Template or Type
   3. Set small time ranges - for example, one hour at a time - on tenants with a high volume of notifications to avoid heavy queries. Move through results in small time chunks until you locate the notification.

How to use Failure Reason and Failure Details

For every failed notification, Mambu stores:

• Failure Reason – a short, categorized error code (for example, INVALID_HTTP_RESPONSE, BLACKLISTED_URL, UNDEFINED_DESTINATION).
• Failure Details – a short text describing the technical cause (for example, HTTP 404 Not Found, provider error message, or exception snippet). Very long messages may be truncated.

Together, these two fields tell you whether the problem is:

• Transient: a network/provider issue, often retried automatically.
• Permanent: a configuration, credentials, or data issue, requiring fixing settings or data.

Investigate failures by channel

Mambu uses the same concepts across channels, but the typical failures differ per channel:

• Webhook failures
• Email failures
• SMS failures

Webhook failures

Only HTTP 2xx responses are considered successful. Anything else results in a failure with a mapped Failure Reason.

Below are common webhook-related reasons and what to do next:

Failure Reason	What it means (high level)	Recommended action
INVALID_HTTP_RESPONSE	The destination endpoint returned a non-2xx HTTP status (for example 400, 401, 404, 500). The status code and (truncated) response body are stored in Failure Details.	Open the notification details and check Failure Details for the exact status code and response body. Fix the underlying issue on your endpoint (for example, incorrect URL, missing or invalid data, server error).
HTTP_ERROR_WHILE_SENDING	A network-level or transport error occurred while sending the request (for example, DNS issue, connection refused, TLS handshake problem, timeout).	Verify that your endpoint is reachable from the public internet, responds within the configured timeout, and has a valid TLS certificate. Check your own logs for matching incoming attempts or failed connections.
BLACKLISTED_URL	Mambu blocked the request because the URL is on a restricted/blacklisted range (for example, internal or private IPs, loopback).	Use a public, allow-listed URL (for example, through an API gateway or reverse proxy). If you need to call internal services, place an authorized endpoint in front of them.
INVALID_HTTP_PROTOCOL	The URL uses a protocol that is not allowed by your environment (for example, http:// instead of https://).	Update the webhook URL to use https://. If you believe http:// should be supported for your environment, contact Mambu Support to discuss options.
MAX_MESSAGE_SIZE_LIMIT_EXCEEDED	The serialized webhook payload is larger than the configured maximum message size.	Simplify the template payload (remove unnecessary fields or very large custom data) or adjust upstream logic so the payload size is smaller.
WEBHOOK_NOTIFICATIONS_DISABLED or similar	The Webhook channel is globally disabled in Mambu settings.	Go to Administration → Notifications → Webhooks (or equivalent configuration) and ensure the channel is enabled. If you do not manage this configuration, contact your internal administrator.
UNDEFINED_DESTINATION	No valid URL could be determined for the notification.	Check the template configuration to ensure the Webhook URL is populated and that any placeholders resolve to a valid URL.

tip

For webhooks, always cross-check your own endpoint logs around the Creation Timestamp of the failed notification to see if the request reached your system and how it was handled.

Email failures

Email notifications depend on a working SMTP configuration and valid recipient addresses.

Common failure reasons:

Failure Reason	What it means	Recommended action
EMAIL_SERVICE_NOT_ENABLED (or equivalent)	The email channel is disabled at organization level.	Check Administration → Notifications / Email Settings and make sure email sending is enabled.
INVALID_SMTP_CREDENTIALS (or similar)	Mambu could not authenticate with your email provider (wrong username/password, token, or host).	Verify SMTP host, port, username, password, and security settings in Administration → Email Settings.
MESSAGING_EXCEPTION / provider error	A transient error happened between Mambu and the email provider (for example, provider outage, temporary rejection).	Review Failure Details for the provider message. If it looks transient, try resending later. If it persists, check your provider’s status page or contact their support.
UNDEFINED_DESTINATION / MISSING_EMAIL_RECIPIENT (exact naming may vary)	No valid email address is available for the recipient.	Open the client/group/user profile and ensure Email Address is present, valid, and not blocked by your provider.
INVALID_EMAIL_ADDRESS (if exposed)	The email address format is invalid or rejected by the provider.	Correct the recipient’s email field to use a valid format (for example, name@example.com).

note

Automated retries typically apply to transient provider/network errors (for example, MESSAGING_EXCEPTION). Permanent issues like invalid credentials or missing recipients require configuration or data fixes.

SMS failures

SMS notifications depend on a configured SMS provider (for example, Twilio) and valid mobile numbers.

Common failure reasons:

Failure Reason	What it means	Recommended action
SMS_SERVICE_NOT_ENABLED (or equivalent)	The SMS channel is disabled at organization level.	Check Administration → Notifications / SMS Settings and ensure SMS sending is enabled.
INVALID_SMS_GATEWAY_CREDENTIALS / provider auth error	Mambu cannot authenticate with your SMS provider (invalid API key/SID/token).	Verify credentials and configuration in Administration → SMS Settings.
SMS_GATEWAY_ERROR / provider error	The SMS provider rejected the message (for example, forbidden destination, unsupported country, throttling).	Inspect Failure Details for the provider’s error code and message. Use your provider’s documentation to interpret it and adjust sender ID, routing, or limits.
UNDEFINED_DESTINATION / MISSING_SMS_RECIPIENT	No valid mobile number was found for the recipient.	On the client/group profile, ensure Mobile Phone 1 is filled in and uses the correct international format (for example, +<country><number>).
INVALID_PHONE_NUMBER (if exposed)	The number format is invalid according to the SMS provider.	Correct the stored phone number to use a valid international format.

tip

If SMS failures are widespread and recent, first check whether provider credentials or configuration were changed around the same time.

Transient vs permanent failures and retries

Mambu uses a retry policy to automatically re-attempt delivery for many transient errors. While implementation details (such as timeout values or retry counts) are configuration-driven and may change, you can think in terms of:

• Usually retried (transient):
  • Network / transport errors (HTTP_ERROR_WHILE_SENDING).
  • Provider temporary errors (for email/SMS).
  • Some non-2xx HTTP responses that indicate rate limiting or temporary unavailability (for example, 429, 5xx), depending on configuration.
• Not retried (permanent until fixed):
  • Misconfiguration in Mambu (channel disabled, invalid credentials).
  • Invalid or missing destination (UNDEFINED_DESTINATION, missing email or mobile).
  • Business or authorization errors from your endpoint (for example, 401, 403, 404 plus provider-specific “invalid address” or “forbidden” messages).
  • Security-related blocks such as BLACKLISTED_URL or invalid protocol.

If a notification remains in a Failed state after retries, the underlying cause must be addressed before further attempts will succeed.

Next steps

If you still cannot identify or fix the issue after following the steps above:

1. Collect the following information:
   • Channel (Email, SMS, Webhook).
   • Template name / ID (if applicable).
   • Notification ID (encoded key) from the communication log.
   • Recipient ID (client/account/group ID).
   • Creation Timestamp and Failure Reason / Failure Details from the log.
2. Export or screenshot the relevant row from the Communications tab.
3. Open a case with Mambu Support for the Notifications team and include all the above details.

This context helps the team quickly correlate your tenant logs with internal telemetry and identify the root cause.