Email Attachment Handling Checklist: Control Size, Access and Version

Choose attachment delivery deliberately, with immutable files, safe hosted URLs, bounded downloads and a tested recipient experience.

SendDart TeamPublished 2026-10-04Updated 2026-10-04

TL;DR

Decide before attaching: treat adding a file as a separate data‑delivery decision and choose whether the file belongs in the email rather than assuming attachment is automatic.
Pick inline content or hosted retrieval deliberately and use an immutable document identity so fetch timing, retries and overwritten URLs do not change what the recipient receives.
Validate limits and failure modes: check per-file, total and endpoint limits, reject oversized files before costly processing, and test missing, expired or wrong-content scenarios.

An attachment is a separate data-delivery decision

Adding a file to an email changes more than the payload size. It changes who can retain the document, how long it remains accessible, what the worker must fetch and which version the recipient receives. Decide whether the file belongs in the email before choosing an SDK field.

A receipt intended for long-term offline storage may fit an attachment. A frequently updated report or sensitive document may fit an authenticated application link better. Neither option is universally safer or more convenient; the decision depends on access, versioning and user needs.

Record the document's purpose and authorized recipient with the notification. The worker should not be able to attach arbitrary files merely because a request includes a path or URL.

Choose inline content or hosted retrieval deliberately

SendDart documents two attachment input forms: base64 content and a hosted path fetched when sending. These forms have different operational implications. Inline content travels with the request, while hosted retrieval depends on the file being available at the time the service fetches it. SendDart attachments.

Use an immutable document identity for either form. A URL that points to a file overwritten later can cause a retry to attach a different version. A signed URL that expires before queued processing begins can fail even though it worked when the job was created.

Do not place public permanent URLs around private documents simply to make sending convenient. Design the access window and storage permissions for the actual workflow. Where a provider must fetch a protected file, use a supported controlled access mechanism and keep its scope narrow.

Account for encoded and decoded size

File bytes, encoded request size and final message size are different measurements. Base64 adds overhead, and message headers and body content also contribute to the transmitted message. Check the service's current per-file, total and endpoint-specific limits rather than relying on a single remembered number.

SendDart's attachment documentation describes restrictions that differ from ordinary text-only sends, including endpoint limitations. Verify the actual sending route before assuming a batch method accepts the same attachment fields as a single-message method.

Reject oversized files before expensive processing where possible. The application should report a useful error or offer an authenticated download alternative, not repeatedly retry a request that can never fit the documented limit.

Treat user-supplied files as untrusted

A filename and declared content type are claims, not proof of safe content. Apply an allowlist appropriate to the business workflow, inspect file properties and scan or quarantine where needed. OWASP's file-upload guidance provides a useful security reference for these controls. OWASP file upload guidance.

Generate storage names independently of untrusted filenames and keep files outside directly executable application paths. Preserve a safe display filename for the recipient without allowing path traversal or header injection through it.

If your application accepts a URL to fetch, restrict it through a deliberate server-side request policy. Do not allow arbitrary internal or credential-bearing destinations. Provider-side safeguards are useful, but the application should still authorize which resource belongs to the notification.

Keep the content snapshot stable

A notification should reference the exact invoice, report or export version it is meant to deliver. Save a checksum or immutable storage identity where useful for audit and integrity. Do not regenerate a changing report on every retry under the same operation key.

If the document is corrected after a send, create a new authorized notification that clearly explains the correction. Reusing the old identity with different bytes makes recovery and support history confusing and may conflict with provider idempotency rules.

Retain enough evidence to establish which version was sent without retaining unnecessary duplicate copies forever. The document system and notification system can share a protected reference rather than each becoming a separate long-term archive of private files.

A resume export is a useful example: in a career product such as Resume Wizard, which shares ownership with SendDart, the notification should refer to the exact document version the user selected. This is an application-design example, not a claim that every export is emailed automatically.

Test the recipient experience

Open controlled messages in the clients relevant to your audience. Check filename display, file type, download behavior and whether the message remains understandable if the attachment is blocked. Include a concise explanation of what the file contains and why the recipient is receiving it.

Do not put essential action instructions only inside a file. A customer should know the purpose and available support path from the email body. For an authenticated link, make the destination and access requirement clear rather than using vague text that resembles a phishing lure.

Review mobile behavior and accessibility of the document itself where relevant. An accessible email pointing to an unreadable image-only invoice still creates a poor experience. The delivery design should include the actual artifact, not stop at the send response.

Recover failures without changing the operation silently

A hosted-file fetch failure may occur before sending, while an interrupted provider handoff can leave the outcome uncertain. Classify the documented response and retain original message evidence. Do not assume every attachment-related error means no mail was attempted.

For a retry, preserve the same authorized file version and supported operation identity. If the URL needs renewed access, ensure it still resolves to the identical document and that the provider's payload contract permits the recovery approach. Otherwise reconcile or create an explicit new operation under a documented policy.

Test missing files, expired access, wrong content type, oversized content and a worker restart. Use fictional documents and controlled recipients. Confirm that logs contain identifiers and safe diagnostics rather than full base64 content or private download credentials.

A dependable attachment workflow connects permission, immutable content and delivery evidence. That is what lets your team answer not only whether an email was accepted, but which document it was authorized to carry.