Blog
Six copy-ready maintenance notices from announcement to completion, with lead times by impact, the right channels and a safe way to pause alerts during the window.
A scheduled maintenance notification template is a pre-written message with placeholders for the affected service, the exact window in UTC, the expected impact and what users need to do. You need one version per stage: announcement, reminder, started, extended, completed and cancelled. Send the first notice 3 to 14 days ahead depending on impact, publish it on your status page and to email subscribers, and pause only the alerts for the components you are actually touching.
This guide gives you all six templates ready to copy, lead times matched to impact, a channel plan and a checklist for silencing monitors without going blind.
Users read maintenance notices quickly, usually to answer one question: will this break something I depend on? A good notice answers that in the first two lines. Every template below is built from the same six fields:
The most common failure is a vague impact line. "Brief interruptions may occur" produces support tickets. "API write requests return 503 for up to 20 minutes; reads keep working" does not.
Lead time should scale with impact, not with how big the work feels internally. These are practical rules of thumb, adjust them to your contracts and customer base:
If your SLA or customer contracts define a notice period for planned maintenance, that period is the minimum, not the target. Check whether maintenance windows count against your uptime commitment before you schedule anything long.
Pick the window from your own traffic data. The quietest hour for a European B2B product is often not the quietest hour for a product with customers in the Americas and Asia.
Use the channel that matches the impact, and always keep one source of truth that every other message links to.
Avoid announcing only in a changelog or on social media. Neither reaches the person whose integration is about to fail.
Replace everything in curly braces. Keep the subject lines consistent so subscribers can see at a glance which stage a message belongs to.
Subject: Scheduled maintenance: {service} on {date}, {start_utc}-{end_utc} UTC
What: We will {plain description, e.g. upgrade our primary database}.
When: {date}, {start_utc} to {end_utc} UTC
({start_local} to {end_local} {local_tz}).
Impact: {component} will be {unavailable | read-only | slower than usual}
for up to {duration}. {unaffected components} keep working normally.
What you need to do: {Nothing | Pause scheduled exports | Retry failed
webhook deliveries after the window}.
Updates: {status_page_url}. Subscribe there to be notified when
the work starts and ends.Subject: Reminder: maintenance on {service} starts in {24 hours | 1 hour}
As announced, {component} will be {impact} from {start_utc} to
{end_utc} UTC on {date}. {unaffected components} are not affected.
{Action, if any}. Follow progress at {status_page_url}.Subject: Maintenance in progress: {service}
We have started the scheduled maintenance on {component}.
As announced, {impact} until {end_utc} UTC at the latest.
Next update: when the work is complete, or by {next_update_utc} UTC.Post this the moment work begins, not when someone remembers. Users who see errors at 02:03 check the status page at 02:04.
Subject: Maintenance extended: {service}, new end {new_end_utc} UTC
The maintenance is taking longer than planned because {reason in one
sentence}. {component} remains {impact}. Your data is {safe and not
affected | being verified before we reopen writes}.
New expected end: {new_end_utc} UTC.
Next update by {next_update_utc} UTC.Publish the extension before the original end time, ideally 15 minutes earlier. A window that silently overruns looks exactly like an outage, and that is how it will be reported.
Subject: Maintenance completed: {service}
The scheduled maintenance finished at {actual_end_utc} UTC.
{component} is fully available again.
{Required follow-up, e.g. Please retry exports that failed during
the window.}
If you still see {symptom}, {reconnect your client | clear cached
DNS | contact {support_contact}}.Subject: Maintenance rescheduled: {service}
The maintenance planned for {old_date}, {old_start_utc}-{old_end_utc} UTC
will not take place. New window: {new_date}, {new_start_utc}-{new_end_utc}
UTC. Reason: {one sentence}. Impact and required actions are unchanged:
{short impact line}.If the maintenance turns into an unplanned outage, stop using these templates and switch to incident communication. The structure in how to write an incident status update covers that handover, including the investigating, identified and monitoring stages.
Leaving monitors active wakes the on-call person for work they already know about. Pausing everything means a real failure in an unrelated system goes unnoticed. Pause only the checks for the components you are touching, set an automatic end time, and verify that alerting is back before you post the completion notice.
Retry-After header, so clients, crawlers and anyone reading monitor results can tell planned unavailability from a crash.A minimal nginx setup for the maintenance response, toggled by a flag file:
server {
# ...
if (-f /etc/nginx/maintenance.flag) {
return 503;
}
error_page 503 @maintenance;
location @maintenance {
root /var/www/maintenance;
add_header Retry-After 1800 always;
rewrite ^ /index.html break;
}
}Enable it with touch /etc/nginx/maintenance.flag and disable it with rm /etc/nginx/maintenance.flag. No reload is needed because the check runs per request. Exclude your health endpoint from this block if you want internal checks to keep reaching the application while external traffic sees the maintenance page.
If you use m0nitor, incident management includes scheduled maintenance windows that are announced on your status page, plus reusable incident templates with placeholders, so the six messages above can be stored once and filled in per window. Status pages support email subscribers and multiple languages, which covers the announcement and completion emails. Alert workflows can notify a channel or call a webhook on monitor events, for example to post into the internal channel your support team watches. Any status page tool with templates and subscriber notifications can follow the same process.
Scale it to impact: 24 to 48 hours for work without visible effect, 3 to 5 days for degraded service, 7 to 14 days for full downtime of a core service, and 30 days or more when customers have to change something on their side. Send reminders 24 hours and 1 hour before anything with visible impact.
Post it on the status page, but skip the email. If something unexpected happens during the work, users will find a matching entry instead of an unexplained error, and you keep subscriber emails meaningful for work that actually affects them.
Use UTC as the primary time, written as an absolute date and time range, and add one local time zone in parentheses if most of your customers are in one region. Avoid relative terms like "tonight" and abbreviations that change with daylight saving time.
Post an extension notice before the original end time with the reason, the new expected end and the time of the next update. If the overrun is caused by an unexpected failure rather than slow progress, switch from maintenance to an incident and communicate it as such.