Troubleshoot Email and SMS Failures

When you configure email or SMS in Mambu Administration, you usually send a test message to confirm that the setup works. Sometimes this test fails without a clear message in the UI.

This page explains:

• A common external cause (for example, Gmail app passwords).
• How to use the Communications view in Mambu to see the exact reason why the test email or SMS failed.

This page applies to:

• Email configuration tests (SMTP / email provider setup).
• SMS configuration tests (SMS provider / gateway setup).

It focuses on failures that occur when you press the Test configuration button in Mambu Administration and:

• No test message arrives at the inbox/phone, and
• The message appears as Failed in the Communication log.

Step 1 – Check common provider requirements (Gmail app passwords)

Many email providers have additional security requirements. A frequent example is Gmail or Google Workspace accounts.

For Google accounts:

• If 2-Step Verification is enabled on the account, regular passwords often cannot be used directly by external apps like Mambu.
• In this case, Google requires an App password – a 16-digit code created specifically for the external app.
• The app password is used instead of your normal account password in the Mambu Email configuration.

For detailed instructions, see your email provider’s documentation.
For Gmail, you can search for “Gmail app passwords” or refer to Google’s help page, for example:
https://support.google.com/mail/answer/185833?hl=en

If your provider requires app passwords or special SMTP settings, and they are not configured correctly in Mambu, the test message will fail with an authentication or connection error. The next section shows how to see that error inside Mambu.

Step 2 – Make sure the Communications view is available

To inspect the technical error for a failed setup test, you must access the Communications view.

If you already see a Communications item in the top navigation bar, you can skip to the next step.

2.1 Add a new Communications view (if missing)

1. Go to Administration > Views.
2. Click the green + button to create a new view.
3. In the dialog:
   • Set Type to Communications.
   • Give it a meaningful name, for example LightWeightCommunication.
4. Assign the appropriate permissions / roles so that the users who need to troubleshoot notifications can access this view.
5. Save the changes.

After saving, the new Communications view (for example LightWeightCommunication) appears in the top horizontal navigation bar of the Mambu UI.

Step 3 – Filter for the test email or SMS notification

Now you can locate the test notification generated by your configuration test.

1. Click the LightWeightCommunication (or the name you chose) view in the top navigation bar.
2. At the top of the page, open the filter dropdown labeled No filter and choose Custom filter….
3. In the filter dialog:
   • Set Type to Email or SMS, depending on which configuration you tested.
   • Set State to Failed.
   • Restrict the Creation date (or similar date field) to Today (or the date and time window when you pressed the test button).
4. Click Apply. The dialog closes and the view refreshes to show only the notifications that match your filter. The failed test notification from your email/SMS configuration test should now be visible in the list.

Step 4 – Add Failure Reason and Failure Details columns

To understand why the setup failed, you need to see the diagnostic fields.

1. Click the green Edit columns button.
2. In the dialog:
   • Enable Include timestamps.
   • Add the following columns (search by name if needed):
     • Failure Reason
     • Failure Details
3. Click Apply changes. The dialog closes and the grid refreshes. The list is typically sorted so that the most recent notification (including your latest test) appears at the top.

Locate the most recent failed notification that matches the time you pressed the test configuration button.

Step 5 – Interpret the error for email and SMS setup

Now use the Failure Reason and Failure Details to understand what went wrong with your setup.

Typical patterns:

5.1 Authentication and credential issues

Common examples:

• Failure Reason: something like INVALID_SMTP_CREDENTIALS, INVALID_SMS_GATEWAY_CREDENTIALS, or a provider-specific credential error.
• Failure Details: may mention “authentication failed”, “invalid username or password”, “invalid token”, or a provider error code.

What to check:

• SMTP or SMS provider username, password, token, or API key.
• For Gmail / Google Workspace:
  • Confirm whether 2-step verification is enabled.
  • If yes, ensure you are using a valid app password for Mambu, not your normal account password.
• Verify that the server host, port, and encryption settings (TLS/SSL) match the provider’s documentation.

5.2 Channel or service disabled

Examples:

• Failure Reason: EMAIL_SERVICE_NOT_ENABLED, SMS_SERVICE_NOT_ENABLED, or similar.
• Failure Details: message indicating the channel is disabled.

What to check:

• In Administration > Notifications > Email / SMS, verify that:
  • The channel is Enabled.
  • Any required provider credentials are configured.
• If you cannot access this area, contact an internal administrator with the necessary permissions.

5.3 Recipient / destination issues

Even for a configuration test, Mambu needs a valid destination:

• Failure Reason: UNDEFINED_DESTINATION, MISSING_EMAIL_RECIPIENT, MISSING_SMS_RECIPIENT, or a provider error indicating invalid address/number.
• What to check:
  • The Test recipient email is valid and properly formatted.
  • The Test phone number is present and uses the correct international format (for example, +<country><number>).
  • The test “To” address/number used in the configuration matches the expected field.

5.4 Provider and network errors

Sometimes the configuration is correct, but the provider or network is having issues:

• Failure Reason: generic provider error or MESSAGING_EXCEPTION / SMS_GATEWAY_ERROR.
• Failure Details: contains an error code or message from the email/SMS provider (for example, throttling, blocked sender ID, invalid region).

What to do:

• Check the provider’s status page or dashboard for reported incidents.
• Use the error code/message from Failure Details in the provider’s documentation.
• Try again later or contact the provider’s support if the error persists.

Next steps

If you still cannot resolve why the email or SMS configuration test fails:

1. Capture:
   • A screenshot of the Email / SMS configuration page in Mambu (with sensitive data masked).
   • A screenshot or export of the failed notification row from the Communications view, including Failure Reason and Failure Details.
2. Note:
   • The tenant name / environment.
   • The approximate timestamp when you pressed the test button.
3. Open a support case with Mambu for the Notifications team and include the above details.

This information allows the support team to correlate your configuration with internal logs and identify the root cause of the failed setup.