Messaging channels are the routes xMatix uses to send messages: email, in-app notifications, mobile push, SMS and chat apps. The Message Log shows what happened to each message. Business rules, workflows, automation scripts, approvals, reminders and report or dashboard subscriptions all send through one shared pipeline. An administrator connects the channels that need a provider account and then uses the log to confirm delivery, resend failures and release messages the flood guard has held.
Overview
Every outbound message goes through the same steps:
- A sender (a business rule, a workflow step, a subscription and so on) asks for a message on one or more channels to one or more recipients.
- xMatix renders the content once, from a template or from inline text.
- It writes one log row for each channel and recipient pair. The row starts as Queued, or as Held if the flood guard stops it.
- A background delivery worker sends the row, retries it if the failure is temporary, and records the result.
You manage two screens:
| Screen | Menu path | What you do there |
|---|---|---|
| Messaging channels | Setup → Feature Hub → Platform → Messaging channels | Connect a provider account for a channel, set its sender, switch it on or off, set quiet hours and a rate limit, and send a test message |
| Message Log | Setup → Platform → Monitoring → Message Log | See every outbound message, filter by channel, status, recipient and date, resend failed messages and release held ones |
When to use it
- Before a rule or workflow sends SMS or chat messages. These channels have no carrier until you add a channel row with a provider account.
- When a user says a notification never arrived. The log shows whether the message was ever created, whether it failed (with the provider's reason) or whether the flood guard held it.
- When an organization-wide alert says outbound messaging was paused. The flood guard has tripped. Find the cause and then release the held messages.
- To keep messages out of the night. Set quiet hours or an hourly rate limit on a channel.
How xMatix handles it
The channels
| Channel | How it is carried | Who the recipient is | Needs a channel row? |
|---|---|---|---|
| The platform's email sending service | An email address | No. A row only adds quiet hours and a rate limit (see Configuration) | |
| In-app | The notification bell in the web app and the mobile app | A user | No |
| Push | Notifications to the user's signed-in mobile devices | A user | No |
| SMS | Your organization's SMS provider account | A phone number | Yes |
| Business chat app | Your organization's business-messaging provider account | A phone number | Yes |
The Channel list on the channel dialog also offers two team-chat apps. You can save rows for them, but the delivery service does not carry them yet, so their messages end as Failed (see Common problems).
What happens to a message
- Recipients are resolved when the message is submitted. A recipient that resolves to nothing (an empty field, say) is skipped: no log row is written and the sender's diagnostics count it as skipped. Phone numbers have spaces, dashes and brackets removed, and a leading
+is kept. - Attachments are email only. Messages that carry attachments, such as report and dashboard subscriptions, are sent straight away instead of through the queue. They still get a log row that shows Sent or Failed.
- Temporary failures are retried. Examples are a provider that is busy (429), a provider error (5xx), a network error, or any error from the email service. xMatix makes up to five attempts, waiting 1, 2, 4 and then 8 minutes between them. Permanent failures go straight to Failed. Examples are an incomplete channel set-up, a channel that is switched off, a 4xx rejection from the provider, or a user with no registered mobile device for push.
- Stuck messages recover on their own. If a delivery worker stops while sending, or a queue hand-off is lost, a recovery sweep sends the message again once it is more than 10 minutes overdue. Delivery is at least once: in rare cases a recipient can receive the same message twice.
- Delivered needs a receipt from the provider. SMS and business-chat providers can report back, which moves Sent to Delivered. A later "undelivered" or "failed" report moves the message to Failed. Email and push never report back, so they stop at Sent.
Statuses
| Status | Meaning |
|---|---|
| Queued | Waiting for the delivery worker. A message deferred by quiet hours or a rate limit, or waiting for a retry, stays Queued until it is due |
| Sending | A delivery attempt is in progress |
| Sent | The provider accepted the message. For in-app messages, the notification has been posted to the user's bell |
| Delivered | The provider confirmed delivery (SMS and business chat only) |
| Failed | Attempts ran out, the failure was permanent, or the provider reported it undelivered. The Error column holds the reason |
| Held | Stopped by the flood guard and waiting for an administrator. Nothing is sent until you release it |
The Status filter also lists Skipped, but delivery never writes that status. Skipped recipients never get a row.
Flood protection
The flood guard is always on and runs when a message is submitted:
- Organization-wide circuit breaker. If your organization has already sent 5,000 messages in the past hour, every new message is Held. Your system administrators also get a critical alert headed "Outbound messaging paused — flood guard tripped".
- Per-recipient limits. Once one address on one channel has received 30 messages in the past hour or 100 in the past day, further messages to it are Held. Replies in a chat conversation with someone who has written to you in the last 24 hours use a separate limit of 200 per hour instead.
- What counts. Only Queued, Sending, Sent and Delivered messages count towards these limits. Held and Failed messages don't, so a quarantine can't keep itself tripped.
These limits are platform defaults that your organization cannot change. A message you release is not checked against the flood guard again.
Opt-outs
Users can switch channels on and off under Notification settings on the notification bell (web), and on the Notifications screen of the mobile app. The switches are In-app, Push, Email, SMS and the business chat app. Only the In-app and Push switches are enforced: messages to a user who has switched those off are skipped. Email, SMS and chat-app messages are addressed to an email address or phone number, not to a user, so the user's switch for those channels does not stop them.
Test traffic
Messages created by an automated test run send only the in-app notification. Email, SMS, push and chat messages are dropped, so tests never reach real people. A dry run sends nothing on any channel.
Prerequisites
- The Manage messaging channels capability to set up channels, and View message log to open the log (see Permissions).
- For SMS or the business chat app: an account with your provider, the sender number it issued, and the account's credential.
- For SMS or the business chat app: an integration app with a Secrets section where you can store the credential (see Credentials and rotation).
Procedure
Step 1 — Store the provider credential
Open the integration app that holds your messaging credentials under Setup → Platform → Integrations, select Secrets, and add the provider's auth token under a reference name you choose, for example sms-auth-token. The value can't be read back afterwards. xMatix finds the credential by its reference name. If more than one integration app has a secret with the same reference name, the channel can't tell which one to use, so keep each reference name unique.
Step 2 — Add the channel
- Go to Setup → Feature Hub → Platform → Messaging channels and select New in the page header.
- Enter a Label such as
Marketing SMS. The Name fills in from the label and can't be changed after you create the row. - Choose the Channel (for example SMS) and the Provider.
- Enter From (sender number / address), the sender number your provider issued, in international format, for example
+15551234567. - Enter the Secret name, the reference name from Step 1, not the credential itself.
- In Settings JSON, enter the provider settings. The SMS provider needs its account identifier, for example
{"accountSid":"AC…"}. Add quiet hours or a rate limit here as well (see Configuration). - Leave Enabled on and select Create.
The row appears in the table with its Label, Channel, Provider, From and Enabled values, and the toast says "Channel created."
Step 3 — Send a test message
On the channel's row, select Test send in the actions column. Enter a recipient (a phone number for SMS, an email address for Email) and select Send. The Test send result window shows queued: and skipped: counts and any diagnostics, such as "in quiet hours; delivery deferred to …".
A queued count of 1 means the message was accepted, not that it was delivered. Open the Message Log, type test in the search box (it matches the Category column), and check that the row reaches Sent (or Delivered). If it shows Failed, hover over View in the Error column to read the reason.
Step 4 — Send messages from a rule or workflow
Channels are used by the features that send messages. Two examples:
- A business rule with the SendMessage action takes a directive such as
template=OrderConfirmed;channels=email;to=field:CustomerEmail;category=orders. Hereto=takesfield:<path>(a field on the record),owner,user:<user id>or a literal address, separated by|. See Business rules. - A workflow's Send Message step does the same from a workflow. See Workflows.
Use the channel keys email, inapp, push and sms in a directive. Templates are chosen by name; see Messaging templates.
Step 5 — Follow delivery in the Message Log
- Go to Setup → Platform → Monitoring → Message Log. It opens on the last seven days.
- Narrow the list with the filters on the second header row: Channel, Status, Recipient (any part of the address; press Enter) and the date range. The search box on the first row searches the rows already loaded, including subject, category and error text.
- Read each row: Created (hover for the exact time), Channel, Status, Recipient, Subject, Attempts, Category and Error (hover over View to read it). In-app and push recipients show as the user's name, with their email address on hover. A user who has since been removed shows as "Unknown user".
Step 6 — Resend a failed message
Fix the cause first: switch the channel on, correct the sender or credential, or ask the user to sign in on the mobile app. Then select Resend on the Failed row. The toast says "Message re-queued for delivery." and the row goes back to Queued. The attempt count carries on from where it stopped. A message that had already used all five attempts gets a single attempt and is not retried again.
Step 7 — Release held messages
- Filter Status to Held and work out what produced the volume. The Category column and the subject point to the sender, for example a business rule or a subscription.
- Fix the source first, for example by deactivating the rule or correcting its condition. Released messages are sent without another flood check.
- Release one message with Release on its row ("Message released for delivery."), or all of them with Release held in the page header. If a Channel filter is selected, Release held releases only that channel's held messages. Each click releases up to 1,000 of the oldest held messages and reports "Released N held message(s)." Click again if more remain.
Fields
Channel dialog
| Field | What it means | Notes |
|---|---|---|
| Label | The name shown in the table | Required |
| Name | The row's stable key | Fills in from the label; read-only after creation |
| Channel | Which channel this row configures: SMS, Email, the business chat app, or one of the two team-chat apps | Required. Keep one row per channel: delivery reads the first row it finds for the channel |
| Provider | The provider account that carries the channel | Required. The list holds the supported SMS and chat-app providers, an email option and a REST connector option |
| From (sender number / address) | The sender number or address | Needed for SMS and chat apps; delivery fails without it |
| Secret name | The reference name of the stored credential | Never the credential itself. See Step 1 |
| Settings JSON | Provider settings plus throttling keys | Saved as entered; a value that isn't valid JSON is ignored when messages are sent |
| Enabled | Whether the channel may send | Switched-off SMS and chat-app channels make their messages Failed at delivery, not skipped |
When you pick the business chat app, the dialog also shows a section for customers messaging you (inbound ordering). That feature is not covered on this page.
Message Log columns
| Column | What it means | Notes |
|---|---|---|
| Created | When the message was submitted | Relative time; hover for the exact date and time |
| Channel | Email, In-app, Push, SMS or the chat app | |
| Status | See Statuses | |
| Recipient | The address, or the user's name for in-app and push | |
| Subject | The rendered subject | Empty for messages sent with no subject |
| Attempts | How many delivery attempts were made | Up to five, plus one per resend |
| Category | The kind of sender, for example Business rule or Test | Set by the sender; business rules default to Business rule |
| Error | The last error or note | A Sent row can carry a note, for example when something sent with the message was refused |
Business rules
- One row is written per channel and recipient. The same address listed twice in one request gets only one row.
- If both a template and inline text are given, the template's subject and body win. Inline text fills anything the template leaves empty. If the template can't be found, the inline content is used and the diagnostics say so.
- A request with no subject and no body creates nothing ("No content — supply a template or inline subject/body.").
- An email that has no HTML body is wrapped in the standard branded layout.
- Quiet hours and the rate limit defer the first attempt. They never drop a message.
- Resend works only on Failed and Held rows. Any other row returns "Only failed or held messages can be re-driven."
Example
A distributor wants an SMS to each customer when their order ships, with no texts at night.
- The administrator stores the SMS provider's auth token as
sms-auth-tokenin the messaging integration app's Secrets. - Under Messaging channels they create Shipping SMS: Channel SMS, the SMS provider, From
+15550100200, Secret namesms-auth-token, and Settings JSON{"accountSid":"AC…","quietHoursStart":21,"quietHoursEnd":8,"quietHoursTz":"Asia/Kolkata","rateLimitPerHour":500}. - Test send to their own mobile number returns
queued: 1. The Message Log row shows Sent, then Delivered a few seconds later. - A business rule on shipment goes live with the directive
channels=sms;to=field:<phone field>;body=Your order has shipped.;category=shipping, where<phone field>is the record field that holds the customer's mobile number. - At 22:30 local time a shipment is saved. The message is created as Queued and deferred to 08:00 the next morning, when it is sent.
Training
Practice exercise
In a sandbox, create an Email channel row with Settings JSON {"quietHoursStart":0,"quietHoursEnd":23,"quietHoursTz":"UTC"}. Then use Test send to your own address. Expected result: the result window shows queued: 1 and a diagnostic that the channel is in quiet hours, with the time delivery is deferred to. The Message Log shows the row as Queued with category Test until 23:00 UTC. If you run the exercise between 23:00 and midnight UTC, the message is sent at once instead. Delete the row afterwards.
Quick reference
- Channels: Setup → Feature Hub → Platform → Messaging channels. Log: Setup → Platform → Monitoring → Message Log.
- Email, in-app and push need no channel row. SMS and the business chat app need one.
- The secret name is a reference; store the value in an integration app's Secrets.
- Five attempts, 1–2–4–8 minutes apart, for temporary failures only.
- Held = flood guard: 5,000 an hour organization-wide, 30 an hour or 100 a day per recipient per channel.
- Fix the source before Release held; released messages skip the flood check.
- Delivered appears only for SMS and the business chat app.
- Only the In-app and Push opt-outs stop messages.
Permissions
Both capabilities are granted on a security profile's Entitlements tab. The built-in SystemAdmin profile has both. See Security profiles.
| Capability | Feature | What it opens | Without it |
|---|---|---|---|
| Manage messaging channels | Metadata Administration | The Messaging channels screen, its New, Edit and Delete actions, and Test send | The menu entry is missing and its requests are refused |
| View message log | Platform Diagnostics | The Message Log, including Resend, Release and Release held | The menu entry is missing and its requests are refused |
Anyone who can view the log can also resend and release messages, so grant View message log only to people you trust to make that call.
Configuration
Throttling keys in Settings JSON
Add these keys to a channel row's Settings JSON. They work on every channel that has a row, including Email.
| Key | Meaning | Example |
|---|---|---|
quietHoursStart | Hour (0–23) when quiet hours begin | 21 |
quietHoursEnd | Hour (0–23) when quiet hours end; may be earlier than the start, so a window can run overnight | 8 |
quietHoursTz | Time zone for the two hours above. If it is empty or not recognized, UTC is used | "Asia/Kolkata" |
rateLimitPerHour | The most messages the channel may create in any rolling hour; the first attempt of later messages waits until the window frees | 500 |
During quiet hours, a new message's first attempt waits until the quiet window ends. If both apply, the later of the two times wins.
What an Email row does and doesn't change
Email is always sent through the platform's email service. An Email row's throttling keys apply, but its Provider, From, Secret name and Enabled switch don't change how email is sent. Email content and layout come from messaging templates.
Related settings
- Templates: Setup → Feature Hub → Platform → Email Templates. A sender's
template=refers to a template by name. - Senders: Business rules (SendMessage action), Workflows (Send Message step), automation scripts, approval notifications and report and dashboard subscriptions.
Common problems
The test send says queued, but nothing arrives
The test only queues the message. Open the Message Log and find the row with category Test:
- Queued with a future time means quiet hours or the rate limit deferred it.
- Failed carries the reason in Error.
- Held means the flood guard stopped it.
"Channel 'sms' is not configured/enabled for this tenant."
There is no Messaging channels row for that channel, or its Enabled switch is off. Add the row or switch it on, then Resend the failed messages.
SMS fails with "config incomplete (need accountSid, auth-token secret, and from address)"
This SMS or chat-app row is missing its account identifier in Settings JSON (accountSid), its From number, or a credential that resolves from Secret name. Check the reference name against the integration app's Secrets list, fix the row, then resend.
A push message failed with "No registered devices for the recipient user."
The user has never signed in on the mobile app, or has signed out on every device. Push can only reach a device the user is signed in on. Ask them to sign in, then resend. In-app notifications still reach them on the web.
A message to the record owner never appears in the log
For email, owner resolves only when the record holds the owner's email address. Otherwise the recipient is skipped and no row is written. Use field:<a field that holds the email address> instead. For in-app and push, owner resolves to the owner user.
Messages for a team-chat channel fail with "Connector registry is not available in this host."
The delivery service does not carry the two team-chat channels yet, whatever you configure on their rows. Use email, in-app or SMS for these notifications instead.
Every new message is Held
The organization-wide breaker tripped. Filter the log to Held, find the sender behind the volume (Category, Subject), fix it, and then select Release held. Messages created after the past hour's count drops below the limit are sent normally again.
Common questions
Why does a message stay at Sent and never reach Delivered?
Delivered needs a delivery receipt from the provider. Only the SMS and business-chat providers send receipts, so email, push and in-app messages correctly stop at Sent. A message that stays at Sent on those channels has not failed: failures always show as Failed with an error. For SMS, a message that stays at Sent usually means the provider has not reported back yet. If the provider later reports it undelivered, the row moves to Failed with the provider's reason.
Can I raise the flood guard limits for my organization?
No. The organization-wide limit (5,000 messages an hour) and the per-recipient limits (30 an hour and 100 a day per channel, or 200 an hour within a live chat conversation) are platform settings. Your organization can't change them. What you control is what happens when they trip: review the held messages, fix the rule or workflow that produced them, and then release them from the Message Log. To spread a large legitimate send, set rateLimitPerHour on the channel. That defers messages instead of holding them.
If I switch a channel off, are its messages skipped?
Not for SMS and the business chat app. Messages are still created as Queued, and each one fails at delivery with "is not configured/enabled for this tenant". When you switch the channel back on, you need to resend them. For email, in-app and push the switch has no effect, because those channels don't depend on a channel row. To stop a sender, deactivate the rule, workflow or subscription itself.
Does a user's opt-out stop email?
No. The bell's notification settings and the mobile Notifications screen offer switches for every channel, but only In-app and Push are enforced. Email, SMS and chat messages go to an address or phone number rather than a user, so the switches for those channels are saved but not applied. To stop a user receiving an email, remove them from the sender's recipients.