Configure communication channels: email, SMS, webhook

Configure Email, SMS, Push, InApp, and Webhook channels in Alphabet. Set credentials, enabled channels, and default channel in appsettings.json.

Each communication channel requires its own configuration in appsettings.json before it can deliver messages. Channels that lack valid credentials or are missing from Communication.EnabledChannels are silently skipped during dispatch. This page covers what you need to supply for each channel and explains the global settings that control which channels are active.

Email channel

The Email channel uses SMTP to deliver messages. Alphabet ships with SendGrid’s SMTP endpoint as the default server, but any SMTP-compatible provider works by updating the host and port.

Configure the channel under the EmailSettings section:

"EmailSettings": {
  "FromEmail": "[e-mail]",
  "FromName": "Alphabet",
  "SmtpServer": "smtp.sendgrid.net",
  "SmtpPort": 587,
  "ApiKey": "<your-smtp-api-key>"
}

Field	Description
FromEmail	The sender address that appears in the From header.
FromName	The display name shown alongside the sender address.
SmtpServer	SMTP host. Default is smtp.sendgrid.net.
SmtpPort	SMTP port. Default is 587 (STARTTLS).
ApiKey	Your SMTP provider’s API key. For SendGrid, create an API key in their dashboard and paste the value here.

To activate the Email channel, add "Email" to Communication.EnabledChannels:

"Communication": {
  "EnabledChannels": ["Email"]
}

Never commit ApiKey to source control. Store it in user secrets, an environment variable, or a secrets vault in non-local environments.

SMS channel

The Sms channel dispatches text messages using Twilio credentials. Configure the channel under the SmsSettings section:

"SmsSettings": {
  "AccountSid": "<your-twilio-account-sid>",
  "AuthToken": "<your-twilio-auth-token>",
  "FromNumber": "[phone]"
}

Field	Description
AccountSid	Your Twilio Account SID, found on the Twilio Console dashboard.
AuthToken	Your Twilio Auth Token from the same dashboard.
FromNumber	The Twilio phone number that sends the SMS. Must be in E.164 format: +1XXXXXXXXXX.

To activate the SMS channel, add "Sms" to Communication.EnabledChannels:

"Communication": {
  "EnabledChannels": ["Sms"]
}

Store AccountSid and AuthToken in user secrets or environment variables. Exposing these credentials allows anyone to send SMS on your account’s behalf.

Push channel

The Push channel delivers notifications to a specific device using a push token. Unlike Email and SMS, there is no global credential block in appsettings.json for push — the device token is supplied per-request in the pushToken field of the request body.

To activate the Push channel, add "Push" to Communication.EnabledChannels:

"Communication": {
  "EnabledChannels": ["Push"]
}

When sending a push notification, include the target device’s token in your request:

{
  "subject": "New message",
  "body": "You have a new notification.",
  "channels": ["Push"],
  "pushToken": "<device-push-token>"
}

Obtain the device push token from your mobile or web client at registration time and store it alongside the user record so you can pass it when sending notifications.

InApp channel

The InApp channel stores messages and delivers them to a specific user inside the application. The recipient is identified by a user GUID supplied in the userId field of the request body. No provider credentials are needed in appsettings.json.

To activate the InApp channel, add "InApp" to Communication.EnabledChannels:

"Communication": {
  "EnabledChannels": ["InApp"]
}

When sending an in-app message, include the target user’s GUID in your request:

{
  "subject": "Account update",
  "body": "Your profile has been updated.",
  "channels": ["InApp"],
  "userId": "3f45ef0f-39d1-4d65-8eaa-5db7c0b8f763"
}

Webhook channel

The Webhook channel POSTs the message payload to a URL you specify per-request in the webhookUrl field. This is useful for integrating with third-party systems or internal services that accept inbound HTTP events. No global credential configuration is required in appsettings.json.

To activate the Webhook channel, add "Webhook" to Communication.EnabledChannels:

"Communication": {
  "EnabledChannels": ["Webhook"]
}

When sending a webhook notification, include the destination URL in your request:

{
  "subject": "Order shipped",
  "body": "Order #12345 has been dispatched.",
  "channels": ["Webhook"],
  "webhookUrl": "https://your-service.example.com/hooks/alphabet"
}

The webhook endpoint must be reachable from the server running Alphabet. Verify that firewalls, VPNs, or private network boundaries do not block outbound requests from the API host to your target URL.

Global communication settings

The Communication section in appsettings.json controls which channels are active and configures diagnostic behavior:

"Communication": {
  "EnabledChannels": [
    "Email",
    "Sms",
    "Push",
    "InApp",
    "Webhook"
  ],
  "DefaultChannel": "Email",
  "EnableDetailedLogging": true
}

Field	Description
EnabledChannels	Array of channel names that Alphabet will dispatch to. Channels not listed here are ignored even if specified in the request body.
DefaultChannel	The channel used when the request does not include a channels array. Default value in the template is "Email".
EnableDetailedLogging	When true, Alphabet writes detailed dispatch logs for each channel. Useful for debugging delivery failures in development.

In production, set EnableDetailedLogging to false to reduce log noise and avoid writing sensitive message content to your log sink.

Multi-channel dispatch example

The following curl request sends the same maintenance notice over all five channels simultaneously:

curl --request POST \
  --url https://your-api-host/api/v1/communications/send \
  --header 'Authorization: Bearer <admin-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "System maintenance",
    "body": "A scheduled maintenance window starts at 22:00 UTC.",
    "channels": ["Email", "Sms", "Push", "InApp", "Webhook"],
    "emailAddress": "[e-mail]",
    "phoneNumber": "[phone]",
    "userId": "3f45ef0f-39d1-4d65-8eaa-5db7c0b8f763",
    "pushToken": "<device-push-token>",
    "webhookUrl": "https://your-service.example.com/hooks/alphabet",
    "isHtml": false
  }'

Troubleshooting

Email not arriving

• Confirm EmailSettings.SmtpServer and EmailSettings.SmtpPort match your provider’s SMTP endpoint.
• Verify that EmailSettings.ApiKey is set to a valid API key. An empty string causes authentication failures.
• Check that "Email" appears in Communication.EnabledChannels.
• Enable EnableDetailedLogging temporarily and inspect the application logs for the SMTP error response.

SMS not delivered

• Confirm SmsSettings.AccountSid and SmsSettings.AuthToken are correct and belong to an active Twilio account.
• Verify that SmsSettings.FromNumber is in E.164 format (e.g., [phone]) and is a number provisioned in your Twilio account.
• Check that the destination phoneNumber in your request is also in E.164 format (e.g., [phone]).
• Check that "Sms" appears in Communication.EnabledChannels.

Webhook not firing

• Ensure the webhookUrl in your request is publicly reachable from the server hosting Alphabet. Local addresses like localhost or private IP ranges are not accessible from an external host.
• Check for firewall rules or network policies that block outbound HTTP requests from the API server.
• Confirm the endpoint returns a 2xx response. Non-2xx responses may be treated as failures in logs.
• Check that "Webhook" appears in Communication.EnabledChannels.