Communication troubleshooting

Which channels actually deliver, why a scheduled notice sat unpublished, what the dead-letter queue does, and why an SMS count means nothing.

Getting started guide for day and boarding schools.

Last updated August 29, 2026

Before diagnosing anything in this module, settle what was actually promised. In-app notifications and SMTP email are the only channels that reach a person. Everything else in the interface that reads like a channel is either a log line or a link builder. Once that is clear, most communication tickets reduce to one of three causes: SMTP is not configured, the recipient has no portal user attached, or the daily job that publishes scheduled content was never installed.

Permission problem or configuration problem?

Composing is a permission question and delivery is a configuration question, and they almost never overlap here. If somebody cannot create or edit a notice, that is their account type, and it fails the same way every time for every audience. If a notice publishes but nobody receives it, the sender is irrelevant - check outbound mail at /settings/email-test, which only Platform Admin and the office Admin role can open, and check whether the intended recipients have active portal users with email addresses. A notice that reaches some people and not others is always the second kind.

Delivery

Symptom	Cause	Fix
In-app alerts appear but no email at all	SMTP is incomplete	SMTP_HOST, SMTP_PORT, SMTP_USER, and SMTP_PASS are all required. Miss any one and the mail transport cannot be built, so every send throws.
Some parents got the email, others did not	Missing address or an opted-out preference	Email goes only to recipients with an address whose email preference is not turned off. A guardian with no portal user is not a recipient at all.
The run reported SMS sent	The bundled provider logs rather than sends	Nothing left the server. High and urgent notices count opted-in recipients and print a single line to the log.
Failures listed under operations but never retried	The queue is a record, not a worker	Fix SMTP first, then publish or resend from the original screen. Dismiss the queued rows once you have.

Audience and timing

Symptom	Cause	Fix
A class notice missed some families	Audience is resolved through active class membership	Students are matched on ACTIVE membership in the current academic year and parents through their guardian records. A student placed in the section after publishing is not reached retrospectively.
Scheduled notice still unpublished	Nothing has triggered the promotion	Schedule scripts/run-school-cron.sh with FEES_CRON_SECRET, or open /notices to force the lazy pass.
Conversation retention removed old threads	The daily purge ran	Conversation and transport retention purges are part of the same daily script. They are irreversible, so confirm the window before installing the job.

Common questions

Quick answers in plain language.

Which notification channels genuinely deliver in Schoolyi?+

Two. In-app notifications are database rows and always work. Email works when SMTP is configured. The bundled SMS provider writes the message to the server log and returns success, so a count of messages sent means a count of messages logged. WhatsApp is not an integration at all - it builds a wa.me link and files it as an in-app notification for a member of staff to click.

A scheduled notice published hours late. What controls the timing?+

Scheduled notices are promoted in two places: by POST /api/notices/cron/publish-scheduled, which the daily script calls, and lazily whenever anyone loads the notices list. Without the cron entry installed, the second path is the only one, so a notice waits until the next person opens /notices.

What does the notification dead-letter queue actually do?+

When a notice email throws, a JSON file is written under uploads/notification-dead-letter, or under NOTIFICATION_DEAD_LETTER_DIR when set, recording the recipient, the error, and an attempt count. The Retry action increments that counter and moves the next-retry timestamp; it does not resend, and nothing consumes the queue automatically. Treat it as a record of what failed, then fix SMTP and send again from the source screen.

Who can create a school notice?+

Any staff or admin account, plus the Teacher and office Admin roles. Student, parent, and vendor accounts cannot. This is broader than most schools assume - a support staff account with no teaching duties can publish to the whole school, so agree the convention rather than relying on the permission.