Skip to content

Send notifications through your own provider

Declare your tenant's own email, SMS or WhatsApp delivery provider, give it its credential, test it and enable it, so the platform's notifications to your people are sent through your account.

Who can do it

A tenant administrator, or a platform super administrator working inside your tenant. The console offers the write controls only to a person who holds the permission to manage the tenant's delivery providers; running a test needs its own permission.

Before you start

  • Your tenant's edition includes your own delivery providers. When it does not, the panel says so and offers no write control. On a customer-operated deployment the platform operator must also have delegated delivery providers to your tenant.
  • Have the provider account ready. The supported mechanisms are SMTP, SendGrid, Microsoft Graph and Gmail for email, Twilio SMS for SMS and Twilio WhatsApp for WhatsApp.
  • A tenant holds at most one provider of each mechanism. Messages on a channel are tried in order: the primary first, then each fallback.

Steps

  1. Open Settings and select the Integrations tab.
  2. On the Delivery providers row, select Manage. The panel opens over the page.
  3. Choose the channel tab: Email, SMS or WhatsApp.
  4. Select Add provider. In the dialog:
    1. Mechanism: the provider type for that channel.
    2. Position: Primary or a fallback position in the channel's chain.
    3. Fill in the transport and sender fields the mechanism asks for, such as the relay host and port for SMTP, or the sender number for Twilio.
  5. Select Save Changes. The console validates the configuration before it saves anything.
  6. On the new provider's row, select Credential, enter the Secret (or, for Gmail, the Service-account key document) and select Seal credential.
  7. Select Test. The test checks that the provider authenticates and is reachable; it sends no message to a real recipient.
  8. When the test passed, select Enable.

To change a provider later, use Edit, Disable or Remove credential on its row.

What you see when it worked

The test ends with Test passed, and the row's Last test column shows Passed. After Enable the row's Status is Active and the provider takes its place in the channel's chain. A passing test proves the provider authenticated and was reachable, not that a message will be delivered.

Every declaration, change and deletion is written to your audit log.

If it fails

What you see Cause What to do
Enable is unavailable: "Run a test against the current configuration before enabling this provider." The provider has no current passing test Run Test and enable it once it passes
Test failed, with the provider's reason The provider could not be reached, or refused the credential Correct the configuration or the credential, then test again
"Included in the Enterprise edition" Your tenant's edition does not include its own delivery providers Contact your account manager
The declaration is refused because the tenant already declares that mechanism One provider per mechanism Edit the existing provider instead
The credential is refused as invalid It is blank, too long, or a Gmail key document lacks a member it needs Paste the full value exactly as issued
A WhatsApp provider cannot be enabled, naming notification types No approved template is mapped for those types Map an approved template for every listed type, then enable
After a credential change or removal the provider is back to Declared Changing or removing a credential discards its test result Give it a credential, test it and enable it again

Twilio SMS and Twilio WhatsApp share one stored credential: removing it through either provider removes it from both.

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/notification/providers/validate (validateNotificationProviderConfig), then POST /api/v3/admin/tenants/{tenantId}/notification/providers (declareNotificationProvider)
API PUT .../notification/providers/{id} (replaceNotificationProviderConfig), PUT .../providers/{id}/credential (replaceNotificationProviderCredential), DELETE .../providers/{id}/credential (deleteNotificationProviderCredential)
API POST .../providers/{id}/test (testNotificationProvider), POST .../providers/{id}/enable (enableNotificationProvider), DELETE .../providers/{id}/enable (disableNotificationProvider)
  • Tenant Settings: what the screen shows and every decision you make on it.