ADR-017 - Email Attachements
Date: 2026-04-16
Status
🤔 Proposed
Context
Users have asked that we increase the file size limit on uploaded documents and remove the multiple‑attachment email routine, in order to reduce the number of emails sent with attachments.
After reviewing the limits in AWS SES (Amazon Web Services – Simple Email Service):
- AWS SES v1 – 10 MB limit
- AWS SES v2 – 40 MB limit (new redesign in 2020)
We are currently using v1.
ADR for multiple attachment emails
Constraints and Best Practice
MIME encoding (the 33% rule):
Emails are Base64‑encoded for attachments, which typically increases file size by around 33%.
A 30 MB PDF file will exceed the 40 MB limit once encoded.
Headers and HTML:
As with the current system, we have allowed 30% (3 MB) of the overall message size for headers and the email content.
Recipient limits:
Just because we can send larger emails does not mean we should. Each receiving email server (e.g.
Gmail, Outlook, or corporate servers) applies its own size cap and will reject emails that exceed it.
MOJ has a real‑world safe limit of < 25 MB, unless using OneDrive links.
Best practice:
For files larger than 10–15 MB, use online storage (i.e. AWS S3) and provide a secure link with a
fixed expiry in the email instead of attaching the document.
This is the approach used by gov.notify for all attachments.
The Uploaded Document Flow
The current flow is:
- File is uploaded and given an arbitrary name
- Saved to disk in tmp/quarantine via UserFilestore
- File size is checked
- File type is checked
- File is streamed to fb-av
- When size, type, and scan results are valid, the file is encrypted and sent to the S3 bucket
- The file in quarantine is deleted
There is an ADR-011-improving-the-antivirus, which highlights issues with file streaming. Smaller files scan more quickly, while larger files can give the impression that the upload page has frozen or crashed.
Changing from v1 to v2
This was a complete redesign and may introduce unknown issues if we simply switch the SDK (Software Development Kit).
Submissions
There will be increased connectivity between the submitter and UserFilestore in order to retrieve attachments and bundle them into the payload sent to AWS SES.
This is the primary cause of delayed jobs (approximately 6–12 per year) when connection issues occur between the two services. Increasing the allowed file size will raise the likelihood of timeouts and may cause delayed jobs to occur more frequently.
Changing the current submission method will also impact other teams that rely on automated workflows.
Testing on the Current System
Test files were uploaded using a test form deployed in the test-dev environment.
| File | Exact size (bytes) | Megabytes (MB) | Human Readable | Result | Reason |
|---|---|---|---|---|---|
| pdf_testfile_1-0.pdf | 1049072 | 1.0005 | 1.0 MB | Pass | |
| pdf_testfile_6-9.pdf | 7,236,080 | 6.9009 | 6.9 MB | Pass | |
| pdf_testfile_7-0.pdf | 7,340,528 | 7.0005 | 7.0 MB | Fail | The file size over the limit |
Timings
| File | Exact size (bytes) | Megabytes (MB) | Upload time |
|---|---|---|---|
| pdf_testfile_1-0.pdf | 1049072 | 1.0005 | 2 seconds |
| pdf_testfile_6-9.pdf | 7,236,080 | 6.9009 | 10 seconds |
During upload, the screen remains static, with the upload button changing from green to yellow.
Options
- Do nothing
- Use v2 and configure maximum sizes
- accept the risk of increased instability and more frequent delayed jobs
- Use v2 and configure to MoJ capped limits
- improve upload feedback
- accept increased risk of delayed jobs
- Use v2 (or remain on v1) and configure a maximum limit
- improve upload feedback
- store files over 7 MB in S3 and provide download links
- Remain on v1 and configure to a maximum limit
- improve upload feedback
- store all files in S3 and provide download links
- Allow form owners to select from the options above (except option 2 and 3)
Option 6 provides the most flexibility for both current and future users.