Template Management - GOV.UK Notify Admin

Overview

Templates are reusable message formats for emails, text messages, and letters. This guide covers everything from creating your first template to advanced features like folders, versioning, and content management.

Template Types

GOV.UK Notify supports three template types:

Email

Send emails with subject lines, HTML formatting, and attachments

SMS

Send text messages up to 918 characters (6 SMS fragments)

Letter

Send physical letters with custom branding and optional attachments

Creating Templates

Access your templates at /services/{service_id}/templates.

Create Email Template

Start New Template

Click “New template” then select “Email” or navigate to /services/{service_id}/templates/add-email.

Name Your Template

Enter a descriptive template name. This is only visible to your team, not recipients.

Use clear names like “Password reset email” or “Monthly newsletter” for easy identification.

Add Subject Line

Write your email subject. You can use placeholders:

Your appointment on ((date)) has been confirmed

Write Email Content

Use the content editor with formatting options:Formatting syntax:

# Heading - Large heading
## Sub-heading - Medium heading
--- - Horizontal line
^ inset text - Highlighted inset box
[link text](https://example.com) - Hyperlinks
Bullet lists with - or *
Numbered lists with 1., 2., etc.

Personalization:

Dear ((name)),

Your reference number is ((reference)).

Thank you,
The ((team_name)) team

Optional: Unsubscribe Link

Enable “Include unsubscribe link” to add automatic one-click unsubscribe for bulk emails.

Unsubscribe links are managed automatically. Users who unsubscribe are tracked system-wide.

Save Template

Click “Create template”. Your template is now ready to use.

Create SMS Template

Start New Template

Select “Text message” when creating a template or go to /services/{service_id}/templates/add-sms.

Name and Write Content

Enter template name and message content. Character counter shows:

Total characters
SMS fragments (1 fragment = ~160 characters)
Cost estimate

Example:

Hi ((name)),

Your appointment is at ((time)) on ((date)).

Location: ((venue))

Reply CONFIRM or CANCEL

Check Character Count

Stay under 918 characters (6 SMS fragments). The counter updates in real-time.

Messages over 918 characters will be rejected. Consider shortening or using email instead.

Save Template

Click “Create template” to finish.

Create Letter Template

Start New Template

Select “Letter” when creating a template.

Creating a letter template automatically creates “Untitled letter template” with placeholder content.

Edit Subject (Heading)

Click “Edit” and update the subject line - this becomes the letter heading.

Write Letter Content

Use the same formatting as email templates:

Headings with # and ##
Bullet points and numbered lists
Inset text with ^
Horizontal rules with ---

Example:

# Your Tax Refund

Dear ((first_name)) ((last_name)),

We're writing to confirm your tax refund of ((amount)).

## What happens next

The refund will be paid into your account within:
- 5 working days for online returns  
- 10 working days for paper returns

Reference: ((reference_number))

Configure Postage

Set default postage class:

Second class - Standard delivery
First class - Faster delivery

Navigate to /services/{service_id}/templates/{template_id}/edit-postage.

Optional: Attach Additional Pages

Add extra pages as PDF at /services/{service_id}/templates/{template_id}/attach-pages:

Upload PDF (max 2MB)
Combined template + attachment must be ≤10 pages
Useful for terms & conditions, maps, etc.

Optional: Welsh Translation

For bilingual letters, add Welsh content:

Go to template settings
Select “Welsh then English”
Provide Welsh translations for subject and content
Letters print Welsh first, then English

Editing Templates

Edit Content

Navigate to template at /services/{service_id}/templates/{template_id}
Click “Edit template”
Make changes to subject, content, or settings
Click “Save”

Breaking changes - If you modify placeholders used by the API, Notify warns you:

Adding new required placeholders
Removing existing placeholders
Renaming placeholders

Confirm you understand the impact before proceeding.

Rename Template (Letters Only)

For letter templates, rename at /services/{service_id}/templates/{template_id}/rename.

Email and SMS templates are renamed by editing the template directly.

Set Reply-to / Sender

Override default sender for specific templates:

Go to template page
Click “Change” next to reply-to/sender
Select from your configured senders
Save changes

This takes you to /services/{service_id}/templates/{template_id}/set-template-sender.

Placeholders and Personalization

Adding Placeholders

Insert dynamic content using double parentheses:

((placeholder_name))

Rules:

Use lowercase and underscores: ((user_name)) ✓
No spaces: ((user name)) ✗
No special characters except underscore
Must be unique within template

Conditional Content

Notify doesn’t support conditional logic in templates. Instead:

Create multiple templates for different scenarios
Handle logic in your application before calling the API
Use different templates for different user segments

Optional Placeholders

All placeholders are required by default. To make content optional:

Provide empty string in API call: {"middle_name": ""}
Handle missing data in your application
Design templates to work with or without optional content

Template Folders

Organize templates into folders for better management.

Creating Folders

Access Template Page

Go to /services/{service_id}/templates.

Create Folder

Click “Manage folders and templates”
Select “Add new folder”
Enter folder name
Click “Save”

Move Templates

Select templates using checkboxes
Choose “Move to” from actions
Select destination folder
Confirm move

Folder Permissions

Restrict access to specific folders:

Navigate to folder at /services/{service_id}/templates/folders/{folder_id}
Click “Manage folder”
At /services/{service_id}/templates/folders/{folder_id}/manage:
- Rename folder
- Select team members who can access
- Save permissions

Folder permissions are inherited by templates inside. Use folders to control which team members can use sensitive templates.

Deleting Folders

Delete empty folders at /services/{service_id}/templates/folders/{folder_id}/delete:

Click “Delete folder”
Confirm deletion

You must empty the folder (move templates out) before deletion. Non-empty folders cannot be deleted.

Template Versioning

Notify automatically versions templates when edited.

View Version History

Access at /services/{service_id}/templates/{template_id}/versions:

See all previous versions
View what changed
Check who made changes
See when edits occurred

View Specific Version

Click a version to see it at /services/{service_id}/templates/{template_id}/version/{version_number}:

Full template content
Metadata (created date, author)
Preview of that version

You cannot send using old versions - they’re for reference only. To revert, manually recreate the old content.

Copying Templates

Copy Within Service

Navigate to Template

Go to the template you want to copy.

Access Copy Function

Click “Make a copy” or navigate to “Copy template” in settings.

Choose Destination

Select folder for the copy (defaults to current folder).

Rename Copy

Template copies as “[Original name] (copy)”. Edit the name.

Save

Click “Create template” to complete the copy.

Copy From Another Service

Start Copy Process

From templates page, select “Copy an existing template” then choose “from another service”.

Select Source Service

At /services/{service_id}/templates/copy, choose the service to copy from.

You must be a team member of both services to copy templates between them.

Browse and Select

Navigate folders in source service and select the template to copy.

Review and Confirm

At /services/{service_id}/templates/copy/{template_id}:

Preview template content
Choose destination folder
Edit template name if needed
Confirm copy

What gets copied:

Template content and placeholders
Subject line (email/letter)
Postage settings (letters)
Unsubscribe link setting (email)
Welsh content (bilingual letters)
Letter attachments

What doesn’t get copied:

Version history
Send history
Sender/reply-to overrides (uses destination service defaults)

Deleting Templates

Navigate to Template

Go to /services/{service_id}/templates/{template_id}.

Delete Template

Click “Delete” and navigate to /services/{service_id}/templates/{template_id}/delete.

Confirm Deletion

Review warning:

“This template was last used [time ago]” or
“This template has not been used within the last year”

Confirm to permanently delete.

Deleted templates:

Cannot be recovered
API calls using this template ID will fail
Message history is preserved
Remove API integrations before deleting

Redacting Templates

Hide personalized content from message history:

Navigate to /services/{service_id}/templates/{template_id}/redact
Confirm redaction
All future messages sent with this template will have placeholder values hidden

Redaction applies to future messages only. Previously sent messages are not affected.

Use cases:

Templates containing sensitive information
Compliance with data protection policies
Hiding personal identifiers from logs

Letter-Specific Features

Letter Attachments

Add PDF attachments to letter templates: Requirements:

PDF format only
Max 2MB file size
Combined template + attachment ≤ 10 pages
Content must be within printable area

Upload process:

Go to /services/{service_id}/templates/{template_id}/attach-pages
Upload PDF
Notify validates and sanitizes the file
Preview shows combined letter + attachment
Save to attach permanently

Managing attachments:

View at template page
Replace by uploading new PDF
Remove at /services/{service_id}/templates/{template_id}/attach-pages/edit

Bilingual Letters (Welsh)

Create Welsh/English bilingual letters:

Enable Bilingual Mode

In template settings, select “Letter languages: Welsh then English”.

Add Welsh Content

Edit Welsh version at /services/{service_id}/templates/{template_id}/edit/welsh:

Welsh subject line
Welsh letter content
Same placeholders as English version

Edit English Content

Edit English version separately. Both versions must use identical placeholders.

Preview Both Versions

Template preview shows:

Welsh pages first
English pages second
Combined page count for postage

Letter Contact Blocks

Set sender contact information for letters:

Configure at service level: /services/{service_id}/service-settings/letter-contacts
Override per template using “Change” on template page
Appears at bottom of letter

Template Search

Find templates quickly:

Use search box on templates page (appears when 7+ templates)
Search by:
- Template name
- Content keywords
- Folder names
Filter by type: All, Email, SMS, Letter

Best Practices

Use Clear Names

Name templates by purpose, not content: “Password reset” not “Template 1”.

Test Before Using

Send test messages to yourself before using templates in production.

Keep Placeholders Simple

Use descriptive names: ((appointment_date)) not ((d)).

Organize with Folders

Group related templates: “Appointments”, “Reminders”, “Confirmations”.

Version Control

Check version history before major edits to track changes.

Monitor Character Count

For SMS, stay well under 918 characters to control costs.

Troubleshooting

Template content too long

SMS: Maximum 918 characters (6 fragments)

Shorten message
Remove unnecessary words
Use abbreviations
Consider email instead

Letters: Maximum 10 pages including attachments

Reduce content
Remove attachment
Split into multiple letters

Cannot add template to folder

Check:

You have permission to access the folder
Folder exists and isn’t deleted
You’re not trying to nest folders (not supported)

Letter attachment upload fails

Common issues:

PDF is corrupted or password-protected
File size exceeds 2MB
Content outside printable area
Combined pages exceed 10

Solutions:

Re-save PDF without protection
Compress PDF or reduce quality
Adjust margins (minimum 5mm)
Remove pages from template or attachment

Placeholder errors in API

If API calls fail with placeholder errors:

Check placeholder names match exactly
Verify all required placeholders are provided
Remove extra whitespace in placeholder names
Check for typos: ((naem)) vs ((name))

Cannot delete template

If deletion is blocked:

Template may be in use by scheduled sends
Wait for scheduled sends to complete
Cancel scheduled sends first
Check API integrations aren’t using it

Uploading Recipients

Send templates to multiple recipients via CSV

Branding

Customize template appearance and sender identity

Managing Services

Configure service-level template settings

Overview

Core Features

User Guides

Configuration

​Overview

​Template Types

Email

SMS

Letter

​Creating Templates

​Create Email Template

​Create SMS Template

​Create Letter Template

​Editing Templates

​Edit Content

​Rename Template (Letters Only)

​Set Reply-to / Sender

​Placeholders and Personalization

​Adding Placeholders

​Conditional Content

​Optional Placeholders

​Template Folders

​Creating Folders

​Folder Permissions

​Deleting Folders

​Template Versioning

​View Version History

​View Specific Version

​Copying Templates

​Copy Within Service

​Copy From Another Service

​Deleting Templates

​Redacting Templates

​Letter-Specific Features

​Letter Attachments

​Bilingual Letters (Welsh)

​Letter Contact Blocks

​Template Search

​Best Practices

Use Clear Names

Test Before Using

Keep Placeholders Simple

Organize with Folders

Version Control

Monitor Character Count

​Troubleshooting

​Related Resources

Uploading Recipients

Branding

Managing Services

Build docs developers (and LLMs) love

Overview

Template Types

Creating Templates

Create Email Template

Create SMS Template

Create Letter Template

Editing Templates

Edit Content

Rename Template (Letters Only)

Set Reply-to / Sender

Placeholders and Personalization

Adding Placeholders

Conditional Content

Optional Placeholders

Template Folders

Creating Folders

Folder Permissions

Deleting Folders

Template Versioning

View Version History

View Specific Version

Copying Templates

Copy Within Service

Copy From Another Service

Deleting Templates

Redacting Templates

Letter-Specific Features

Letter Attachments

Bilingual Letters (Welsh)

Letter Contact Blocks

Template Search

Best Practices

Troubleshooting

Related Resources