Introduction

Sending PDF attachments through Amazon SES requires a raw MIME email, because simple send APIs do not support binary attachments directly. The message must include proper boundaries, content types, and base64 encoding.

In Node.js, you can generate this MIME payload manually or with a helper library. Then pass the raw bytes to SES SendRawEmail or its modern equivalent in the SDK.

A reliable implementation validates MIME structure locally before sending, so delivery debugging is focused on policy and identity issues instead of malformed payloads.

Core Sections

Understand the failure mode

Quick fixes usually solve the visible symptom and skip the reason the behavior appears. That makes the same issue return in another environment. Start by identifying the exact boundary where data format, lifecycle timing, or control flow changes.

Write one input and one expected output before modifying implementation details. This converts debugging into a deterministic process and creates a clear contract for reviewers.

Apply a repeatable implementation pattern

Good implementation is not only about passing the current test. It should also establish a shape that future contributors can follow without guessing hidden assumptions. Keep configuration explicit, avoid hidden global state, and isolate side effects from pure logic.

1import { SESClient, SendRawEmailCommand } from "@aws-sdk/client-ses";
2import fs from "node:fs";
3
4const ses = new SESClient({ region: "us-east-1" });
5const pdfBase64 = fs.readFileSync("invoice.pdf").toString("base64");
6const boundary = "NextPartBoundary";
7
8const rawEmail = [
9  "From: [email protected]",
10  "To: [email protected]",
11  "Subject: Invoice",
12  "MIME-Version: 1.0",
13  `Content-Type: multipart/mixed; boundary="${boundary}"`,
14  "",
15  `--${boundary}`,
16  "Content-Type: text/plain; charset=utf-8",
17  "",
18  "Please find the invoice attached.",
19  `--${boundary}`,
20  "Content-Type: application/pdf; name="invoice.pdf"",
21  "Content-Transfer-Encoding: base64",
22  "Content-Disposition: attachment; filename="invoice.pdf"",
23  "",
24  pdfBase64,
25  `--${boundary}--`,
26].join("
27");
28
29await ses.send(new SendRawEmailCommand({
30  RawMessage: { Data: Buffer.from(rawEmail) },
31}));

This baseline example is intentionally concise and runnable. In production systems, keep the same structure and move environment-specific values into configuration sources.

Validate with a smoke test

After coding, run a short smoke test that covers the critical path end to end. Smoke checks provide fast confidence and catch integration issues early. Follow with targeted failure cases that represent the most likely operational mistakes.

1function chunkBase64(value, size = 76) {
2  const out = [];
3  for (let i = 0; i < value.length; i += size) {
4    out.push(value.slice(i, i + size));
5  }
6  return out.join("
7");
8}
9
10const safePdfBase64 = chunkBase64(pdfBase64);
11console.log(safePdfBase64.length > 0);

Run validation locally and in continuous integration using the same command shape. Consistent execution paths reduce drift and prevent merge-time surprises.

Hardening for production use

After functional correctness, improve observability and failure clarity. Include enough context in logs to diagnose incidents quickly, such as relevant identifiers, endpoint details, or version metadata. Prefer explicit failure paths instead of silent fallback behavior.

Document assumptions near the code, including environment dependencies, resource limits, or format expectations. Explicit assumptions make upgrades safer and reduce review time.

Maintenance and regression strategy

Every resolved bug should add a regression test that would fail before the fix and pass after it. Keep tests compact, deterministic, and easy to run in local development.

When new requirements arrive, extend the same structure instead of adding one-off conditionals. Consistent structure prevents complexity spikes and keeps long-term maintenance predictable.

Common Pitfalls

• Sending binary bytes without base64 encoding creates corrupted attachments.
• Using incorrect MIME boundaries causes SES to reject or misparse messages.
• Skipping sender or domain verification blocks delivery in many accounts.
• Forgetting CRLF line endings can break strict MIME parsers.
• Large attachments beyond SES limits fail silently without explicit checks.

Summary

• Use raw MIME email format for SES attachments.
• Encode PDF content in base64 and include correct headers.
• Construct boundaries and line endings carefully.
• Verify sender identity and account sending permissions.
• Validate attachment size and payload format before send.