Uploading Recipients

Overview

GOV.UK Notify allows you to send messages to multiple recipients by uploading CSV files. This guide covers CSV formatting, contact lists, batch sending, and troubleshooting upload issues.

CSV File Requirements

Supported Formats

Notify accepts:

.csv - Comma-separated values
.xlsx - Microsoft Excel (modern format)
.xls - Microsoft Excel (legacy format)
.ods - OpenDocument spreadsheet
.tsv - Tab-separated values
.txt - Plain text with delimiters

File size limit: 2MB. Maximum 50,000 rows for batch sends.

Column Structure

Your CSV must have:

Header row - Column names (case-insensitive)
Data rows - Recipient information and personalization

Email Template CSVs

email address,name,reference
[email protected],Alice Smith,ACC-001
[email protected],Bob Jones,ACC-002

Required column:

email address - Valid email address

Optional:

Template placeholder columns (e.g., name, date)
reference - Your own reference identifier

SMS Template CSVs

phone number,name,appointment_time
07700900123,Alice Smith,3pm on Monday
07700900456,Bob Jones,10am on Tuesday

Required column:

phone number - UK mobile number (or international if enabled)

Formats accepted:

07700900123
+447700900123
0044 7700 900 123
+44 (0) 7700 900123

Letter Template CSVs

address line 1,address line 2,address line 3,address line 4,address line 5,address line 6,address line 7,name
Alice Smith,123 Example Street,,,London,,SW1A 1AA,
Bob Jones,Department of Examples,10 Whitehall,,,London,SW1A 2AA,

Required columns (first 7 columns must be address lines):

address line 1 - Recipient name or first line
address line 2 - Building/street
address line 3 - Town/city or postcode
address line 4 - (optional)
address line 5 - (optional)
address line 6 - (optional)
address line 7 - Postcode (if not in line 3)

At minimum, you need addressee name (line 1), street (line 2), and postcode (line 3 or 7).

Placeholder Columns

Add columns for template personalization:

email address,name,due_date,amount
[email protected],Alice,15 January,£50.00

If your template contains ((name)), ((due_date)), and ((amount)), include those as columns.

Column names must exactly match placeholder names (case-insensitive). Spaces and underscores are interchangeable.

Downloading Example CSVs

Get a correctly formatted example:

Navigate to your template
Click “Send messages”
Download the example CSV from /services/{service_id}/send/{template_id}.csv

The example includes:

All required columns for that template type
Template placeholder columns
Sample data in the correct format

Sending Messages from CSV

Navigate to Template

Go to your template at /services/{service_id}/templates/{template_id} and click “Send”.

Upload CSV

At /services/{service_id}/send/{template_id}/csv:

Click “Choose file” or drag and drop
Select your CSV file
Click “Continue”

Notify validates your file immediately for:

File format issues
Virus scanning
File size limits

Review Recipients

Notify shows you:

Total number of recipients
First 50 rows as a preview
Any errors or warnings
Personalization preview for first recipient

Error types displayed:

Invalid email addresses or phone numbers
Missing required columns
Empty recipient fields
Trial mode restrictions

Choose Sender (if applicable)

If your service has multiple senders:

Select reply-to email address (for email templates)
Select SMS sender ID (for SMS templates)
Choose letter contact block (for letter templates)

Send Now or Schedule

Options:

Send now - Messages sent immediately
Schedule for later - Choose date and time (up to 7 days ahead)

Scheduled sends use midnight, midday, or hourly slots in your local timezone.

Confirm and Send

Review the summary:

Recipient count
Template preview
Send time
Sender details

Click “Send [X] messages” to confirm.

Contact Lists

Contact lists are reusable CSV files stored in Notify for repeated sends.

Creating Contact Lists

Upload CSV

Navigate to /services/{service_id}/upload-contact-list and upload a CSV containing only recipient addresses.Format:

email address
[email protected]
[email protected]  
[email protected]

phone number
07700900123
07700900456
07700900789

Validate List

Notify checks at /services/{service_id}/check-contact-list/{upload_id}:Requirements:

Only ONE column (email address OR phone number)
Maximum 50,000 rows
All addresses must be valid
In trial mode, must be team members or guest list

Common errors:

Multiple columns (not allowed)
Empty rows
Invalid addresses
Mixed email and phone numbers

Save Contact List

Give your list a name and save it. The list becomes available for future sends.

Using Contact Lists

Send to a saved list:

Go to Uploads page
Click on your contact list
Click “Send messages”
Choose a template
Confirm and send

Contact lists are perfect for regular communications like newsletters, weekly updates, or standing notifications.

Managing Contact Lists

At /services/{service_id}/contact-list/{contact_list_id}:

View - See recipients and send history
Download - Export as CSV
Delete - Remove the contact list

Deleting a contact list doesn’t affect previously sent messages, only future sends.

Uploading Letters (Precompiled PDFs)

Send pre-designed letter PDFs without using templates.

Upload Requirements

Prepare PDF

Your PDF must:

Be a valid PDF document
Not be password-protected or encrypted
Have readable text (not be corrupted)
Meet Notify’s letter specifications

Upload PDF

Go to /services/{service_id}/upload-letter:

Choose your PDF file (max 2MB)
Upload for validation

Notify sanitizes the PDF to ensure it meets postal requirements.

Preview and Validate

At /services/{service_id}/preview-letter/{file_id}, Notify:

Extracts the address from your PDF
Counts pages (max 10 pages)
Checks printable area
Detects invalid content

Validation errors:

content-outside-printable-area - Content too close to edges
Invalid address format
Corrupted PDF

Choose Postage

Select postage class:

Second class - 2-3 working days
First class - 1-2 working days
Europe - International European addresses
Rest of world - International non-European addresses

Send Letter

Confirm to submit for printing. Letters are processed and posted according to the daily print deadline.

Viewing Uploaded Letters

See all uploaded letters at /services/{service_id}/uploaded-letters/{print_day}:

Grouped by print day
Shows recipient preview
Links to individual letter status
Pagination for large batches

CSV Validation Errors

Common Issues

Missing columns

Error: Required column not foundSolution:

Ensure header row has exact column names
Check spelling: email address not email
For letters: All 7 address line columns required

Invalid email addresses

Error: Row X has an invalid emailSolution:

Check for typos: user@examplecom should be [email protected]
Remove spaces: user @example.com should be [email protected]
Validate domain exists

Invalid phone numbers

Error: Row X has an invalid phone numberSolution:

Use UK format: 07700900123 or +447700900123
Enable international SMS for overseas numbers
Remove letters: Mobile should be a number
Check for extra characters

Too many columns

Error: Contact lists can only have one columnSolution: For contact lists, include ONLY the recipient column:

Either email address OR phone number
Remove all other columns
Use regular CSV upload for templates with personalization

File too large

Error: File exceeds 2MB or 50,000 rowsSolution:

Split into multiple files
Remove unnecessary columns
Check for hidden data in spreadsheet
Export as plain CSV to reduce size

Empty recipient field

Error: Row X has a missing email/phone/addressSolution:

Fill in all required fields
Remove rows with empty recipients
Check for whitespace-only cells

Trial mode restrictions

Error: Can only send to team members in trial modeSolution:

Add recipients to your team or guest list
Request to go live
Use only team member addresses for testing

File encoding issues

Error: Cannot read CSV fileSolution:

Save as UTF-8 encoding
Re-save from spreadsheet software
Check for special characters
Try different file format (.xlsx instead of .csv)

Letter Upload Errors

PDF Validation Issues

Cannot read PDF

PDF is corrupted
File is not actually a PDF
Solution: Re-save or recreate the PDF

Content outside printable area

Content too close to page edges
Margin requirements: 5mm minimum
Solution: Adjust margins in design software

Invalid address

Address cannot be parsed
Missing postcode
Solution: Ensure clear address block on first page

Too many pages

Exceeds 10 page maximum
Solution: Split into multiple letters or reduce content

Best Practices

Test with Small Batches

Upload 5-10 rows first to verify formatting before sending to thousands.

Use Consistent Formatting

Keep phone numbers in same format throughout CSV for better validation.

Download Examples

Always start with Notify’s example CSV for your template type.

Validate Addresses

Clean your data before upload - remove duplicates and invalid entries.

Save Contact Lists

For recurring sends, save contact lists instead of re-uploading CSVs.

Schedule Wisely

Schedule large batches during off-peak hours to avoid rate limiting.

Performance Tips

Large File Uploads

For files with 10,000+ recipients:

Split files - Break into 5,000-row chunks
Remove formatting - Use plain CSV, not Excel with styling
Minimize columns - Only include required fields and placeholders
Schedule overnight - Spread large sends across time

Retry Strategy

If validation fails:

Fix errors shown in red
Re-upload corrected file
Notify remembers your sender selection
Previous uploads are stored for reference

Viewing Upload History

Access all uploads at /services/{service_id}/uploads:

Recent uploads - CSVs and contact lists
Scheduled jobs - Future sends
Sent batches - Completed sends with stats
Contact lists - Saved recipient lists

Each upload shows:

File name
Recipient count
Send status
Timestamp
Template used

Template Management

Create templates for CSV sends

Managing Services

Configure daily limits and settings

Overview

Core Features

User Guides

Configuration

Overview

CSV File Requirements

Supported Formats

Column Structure

Email Template CSVs

SMS Template CSVs

Letter Template CSVs

Placeholder Columns

Downloading Example CSVs

Sending Messages from CSV

Contact Lists

Creating Contact Lists

Using Contact Lists

Managing Contact Lists

Uploading Letters (Precompiled PDFs)

Upload Requirements

Viewing Uploaded Letters

CSV Validation Errors

Common Issues

Letter Upload Errors

PDF Validation Issues

Best Practices

Test with Small Batches

Use Consistent Formatting

Download Examples

Validate Addresses

Save Contact Lists

Schedule Wisely

Performance Tips

Large File Uploads

Retry Strategy

Viewing Upload History

Template Management

Managing Services

Build docs developers (and LLMs) love

Overview

Core Features

User Guides

Configuration

​Overview

​CSV File Requirements

​Supported Formats

​Column Structure

​Email Template CSVs

​SMS Template CSVs

​Letter Template CSVs

​Placeholder Columns

​Downloading Example CSVs

​Sending Messages from CSV

​Contact Lists

​Creating Contact Lists

​Using Contact Lists

​Managing Contact Lists

​Uploading Letters (Precompiled PDFs)

​Upload Requirements

​Viewing Uploaded Letters

​CSV Validation Errors

​Common Issues

​Letter Upload Errors

​PDF Validation Issues

​Best Practices

Test with Small Batches

Use Consistent Formatting

Download Examples

Validate Addresses

Save Contact Lists

Schedule Wisely

​Performance Tips

​Large File Uploads

​Retry Strategy

​Viewing Upload History

​Related Resources

Template Management

Managing Services

Build docs developers (and LLMs) love

Overview

CSV File Requirements

Supported Formats

Column Structure

Email Template CSVs

SMS Template CSVs

Letter Template CSVs

Placeholder Columns

Downloading Example CSVs

Sending Messages from CSV

Contact Lists

Creating Contact Lists

Using Contact Lists

Managing Contact Lists

Uploading Letters (Precompiled PDFs)

Upload Requirements

Viewing Uploaded Letters

CSV Validation Errors

Common Issues

Letter Upload Errors

PDF Validation Issues

Best Practices

Performance Tips

Large File Uploads

Retry Strategy

Viewing Upload History

Related Resources