Documentation Index
Fetch the complete documentation index at: https://mintlify.com/alphagov/notifications-api/llms.txt
Use this file to discover all available pages before exploring further.
These endpoints are used by the admin interface to manage templates. All endpoints require admin authentication.
Create Template
POST /service/{service_id}/template
Create a new template for a service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Request Body
{
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name))",
"content": "Hi ((name)),\n\nWelcome to our service!",
"service": "service-uuid",
"created_by": "user-uuid",
"parent_folder_id": "folder-uuid",
"process_type": "normal"
}
Template Types
| Type | Description |
|---|
email | Email template |
sms | SMS template |
letter | Letter template |
Process Types
| Type | Description |
|---|
normal | Standard priority |
priority | High priority (faster delivery) |
bulk | Bulk sending (may be slower) |
Response
{
"data": {
"id": "template-uuid",
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name))",
"content": "Hi ((name)),\n\nWelcome to our service!",
"version": 1,
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2023-01-01T00:00:00Z",
"created_by": {
"id": "user-uuid",
"name": "Admin User"
},
"service": "service-uuid",
"archived": false
}
}
201 Created
For letter templates, if no postage is specified, it defaults to second class.
Update Template
POST /service/{service_id}/template/{template_id}
Update an existing template. Each update creates a new version.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
Request Body
{
"name": "Updated Welcome Email",
"subject": "Welcome to ((service_name)) - Updated",
"content": "Hi ((name)),\n\nWelcome! We've updated our message.",
"created_by": "user-uuid"
}
Response
{
"data": {
"id": "template-uuid",
"name": "Updated Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name)) - Updated",
"content": "Hi ((name)),\n\nWelcome! We've updated our message.",
"version": 2,
"updated_at": "2023-01-02T00:00:00Z"
}
}
Get All Templates for Service
GET /service/{service_id}/template
Retrieve all templates for a service.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Response
{
"data": [
{
"id": "template-uuid-1",
"name": "Welcome Email",
"template_type": "email",
"version": 2,
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2023-01-02T00:00:00Z",
"archived": false
},
{
"id": "template-uuid-2",
"name": "Reminder SMS",
"template_type": "sms",
"version": 1,
"created_at": "2023-01-01T00:00:00Z",
"archived": false
}
]
}
Get Template by ID
GET /service/{service_id}/template/{template_id}
Retrieve a specific template (latest version).
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
Response
{
"data": {
"id": "template-uuid",
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name))",
"content": "Hi ((name)),\n\nWelcome to our service!",
"version": 2,
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2023-01-02T00:00:00Z",
"created_by": {
"id": "user-uuid",
"name": "Admin User"
},
"service": "service-uuid",
"archived": false,
"folder": "folder-uuid",
"redact_personalisation": false,
"postage": "second"
}
}
Preview Template
GET /service/{service_id}/template/{template_id}/preview
Preview a template with personalisation values.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
Query Parameters
Provide personalisation values as query parameters:
?name=John&service_name=My Service
Response
{
"id": "template-uuid",
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to My Service",
"content": "Hi John,\n\nWelcome to our service!",
"version": 2
}
Error Response
If required personalisation is missing:
{
"result": "error",
"message": {
"template": ["Missing personalisation: name, service_name"]
}
}
400 Bad Request
Get Template Version
GET /service/{service_id}/template/{template_id}/version/{version}
Retrieve a specific version of a template.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
version | integer | The version number |
Response
{
"data": {
"id": "template-uuid",
"name": "Welcome Email",
"template_type": "email",
"subject": "Welcome to ((service_name))",
"content": "Hi ((name)),\n\nWelcome to our service!",
"version": 1,
"created_at": "2023-01-01T00:00:00Z"
}
}
Get All Template Versions
GET /service/{service_id}/template/{template_id}/versions
Retrieve all versions of a template.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
template_id | uuid | The template ID |
Response
{
"data": [
{
"id": "template-uuid",
"name": "Updated Welcome Email",
"version": 2,
"created_at": "2023-01-02T00:00:00Z",
"created_by": "user-uuid"
},
{
"id": "template-uuid",
"name": "Welcome Email",
"version": 1,
"created_at": "2023-01-01T00:00:00Z",
"created_by": "user-uuid"
}
]
}
Archive Template
POST /service/{service_id}/template/{template_id}
Archive a template by setting the archived flag.
Request Body
{
"archived": true,
"created_by": "user-uuid"
}
Response
{
"data": {
"id": "template-uuid",
"archived": true,
"version": 3
}
}
Archiving a template also archives any associated email attachment files.
Redact Template
POST /service/{service_id}/template/{template_id}
Redact personalisation data from a template’s notification history.
Request Body
{
"redact_personalisation": true,
"created_by": "user-uuid"
}
Response
Status Code: 200 OK
Redacting a template prevents viewing personalisation data in sent notifications. This is useful for GDPR compliance.
Update Template Reply-To
POST /service/{service_id}/template/{template_id}
Update the reply-to address or letter contact for a template.
Request Body
For email templates:
{
"reply_to": "reply-to-email-uuid"
}
{
"reply_to": "letter-contact-uuid"
}
{
"reply_to": "sms-sender-uuid"
}
Response
{
"data": {
"id": "template-uuid",
"service_letter_contact_id": "letter-contact-uuid",
"version": 2
}
}
Get Precompiled Letter Template
GET /service/{service_id}/template/precompiled
Retrieve the precompiled letter template for a service. This is a special hidden template used for sending letters from PDF files.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
Response
{
"id": "template-uuid",
"name": "Pre-compiled PDF",
"template_type": "letter",
"hidden": true,
"is_precompiled_letter": true
}
Preview Letter Template from Notification
GET /service/{service_id}/template/preview/{notification_id}/{file_type}
Generate a preview of a sent letter notification.
Path Parameters
| Parameter | Type | Description |
|---|
service_id | uuid | The service ID |
notification_id | uuid | The notification ID |
file_type | string | Either pdf or png |
Query Parameters
| Parameter | Type | Description |
|---|
page | integer | Page number for PNG previews |
Response
{
"content": "base64-encoded-file-content",
"metadata": {
"message": "content-outside-printable-area",
"invalid_pages": ["1", "3"]
}
}
Template Content Validation
SMS Templates
- Maximum length: Automatically calculated based on GSM-7 encoding
- Character limit: 918 characters (6 SMS segments)
- Personalisation fields count towards the limit
Email Templates
- Subject line: No strict limit but keep under 100 characters for deliverability
- Content: No strict limit
- Supports Markdown formatting
Letter Templates
- QR codes: Data must not exceed 500 characters
- Postage: Must be
first or second class
- Content must fit within printable area
Personalisation
Templates support personalisation using double parentheses:
Hi ((name)),
Your reference number is ((reference)).
{
"personalisation": {
"name": "John Smith",
"reference": "ABC123"
}
}