KoltrixAttachments in transactional email: size, type, options
Attaching invoices and reports raises size, security and deliverability concerns. When to attach, when to link, and how to keep attachments safe.
On this page(10 sections)
Attaching the invoice PDF feels like the obviously helpful thing to do. Sometimes it is.
Sometimes it makes the message larger, slower, more likely to be filtered and a worse security risk than a link would be. The decision deserves more thought than it usually gets.
The case for attaching
Attachments have real advantages for certain documents:
- Offline access and records. Accountants and finance teams often want invoices and receipts as files they can archive or forward to an expense system without logging into anything.
- No account required. A recipient who is not a user of your product, such as a customer's accounts payable department, can open an attached invoice but may not be able to sign in to download it.
- Permanence. A link can break when the account is closed or the document is regenerated. An attachment is a snapshot.
- Expectations. In some industries and countries, customers expect invoices to arrive as attached PDFs.
The case for linking
Links win in other situations:
- Size. Attachments are base64-encoded for transport, which inflates them by about a third. A 3 MB PDF becomes roughly 4 MB on the wire. Large messages are slower to deliver and some receivers impose size limits well below what your provider accepts.
- Sensitive content. A link behind authentication can be revoked, expired and logged. An attachment, once delivered, lives forever in every mailbox it reaches, including forwards.
- Freshness. Reports and statements that may be corrected later are better served live.
- Deliverability. Attachments, especially of certain types, receive extra scrutiny from filters. Plain, small messages are the easiest to deliver.
- Accessibility and mobile. Opening attachments on a phone is clumsier than following a link to a responsive page.
A practical decision guide
| Document | Recommendation |
|---|---|
| Invoice or receipt for a business customer | Attach a small PDF, and also link to it |
| Payment confirmation for consumers | Link; include key amounts in the email body |
| Monthly usage report | Link to the dashboard; optionally attach a summary PDF |
| Contract or document requiring signature | Link to the signing flow |
| Data export or large file | Link with an expiring, authenticated download |
| Anything containing sensitive personal or financial data | Link behind authentication |
| Calendar invitation | Attach as text/calendar (that is how invitations work) |
The hybrid approach, attaching a small document and linking to the canonical version, serves both the archivist and the person on a phone.
File types: what to send and what to avoid
Stick to formats that are expected and safe:
- PDF for documents. Generate it server-side, keep it small, and avoid embedded scripts or active content.
- CSV for small tabular data, though spreadsheet applications can interpret cells beginning with
=,+,-or@as formulas. Sanitize values to prevent CSV injection. - ICS (
text/calendar) for calendar events. - Images such as PNG or JPEG, when the image itself is the content.
Avoid sending, and expect receivers to block or quarantine:
- Executables and scripts (
.exe,.js,.bat,.scrand the like). - Office documents with macros.
- Archives such as ZIP files, especially password-protected ones, which filters cannot inspect and attackers commonly use. Many organizations quarantine them by policy.
- Unusual or double extensions such as
invoice.pdf.exe.
Even legitimate archives can cause delivery problems because filters cannot see inside them. If you need to send multiple files, link to a download page instead.
Size limits
There is no single universal limit. Major mailbox providers accept messages in the tens of megabytes, but corporate mail gateways often cap messages lower, and the base64 overhead counts against the limit. Your sending provider has its own maximum too.
Practical guidance:
- Keep attachments well under 1 MB where you can. Most invoices and receipts can be a few hundred kilobytes at most.
- Compress images inside PDFs, and avoid embedding full font files when a standard font will do.
- Treat anything over a few megabytes as a candidate for a link.
- Monitor bounces with size-related errors, which often mention message size or a 552 reply code.
Building attachments correctly
Attachments belong in a multipart/mixed part alongside the message body, never inside multipart/alternative:
multipart/mixed
├── multipart/alternative
│ ├── text/plain
│ └── text/html
└── application/pdf
Content-Disposition: attachment; filename="invoice-A-10293.pdf"
Content-Transfer-Encoding: base64Use your mail library or provider API to construct this rather than assembling MIME by hand. Give each attachment:
- An accurate
Content-Type. Content-Disposition: attachmentwith a clear filename containing no personal data beyond what is necessary, such as an invoice number rather than a customer's full name.- ASCII-safe filenames where possible. Non-ASCII filenames require RFC 2231 encoding, which libraries handle, but some older clients display them poorly.
Security considerations
Attachments you generate can still be abused:
- Do not attach user-uploaded files to emails sent from your domain without scanning and strict type checks. Otherwise your domain becomes a delivery mechanism for someone else's malware.
- Do not include data the recipient should not have. Generate the document for the specific recipient and verify authorization before attaching, exactly as you would for a download endpoint.
- Avoid password-protected PDFs as a security measure when the password travels in the same email or a predictable format. It adds friction without adding much protection.
Write the body as if the attachment were missing
Some recipients will never open the attachment, and some security gateways will strip it. The email body should stand on its own: state the amount, the invoice number, the due date and how to pay or view the document online. The attachment is a convenience, not the message.
Checklist
- Decide per template: attach, link, or both.
- Keep attachments small and in safe formats: PDF, CSV, ICS, standard images.
- Never send executables, macro-enabled documents or archives.
- Place attachments in
multipart/mixedwith correct type, disposition and filename. - Put every key fact in the email body itself.
- Use authenticated, expiring links for sensitive or large content.
- Scan or forbid user-supplied files in emails from your domain.
Bottom line
Attach small, expected documents such as business invoices and calendar invites, and link everything that is large, sensitive or likely to change. Keep attachments in safe formats, build the MIME structure correctly, and make sure the email body works on its own when the attachment is never opened.
Start with Koltrix
Your domain, one inbox, and an API that sends.
A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.
