Why Your Image Isn't Rendering in Email: Understanding Base64 Encoding for 2026

The bug report came in at 9am: 'Profile pictures are not loading in our welcome email.' Four engineers, ninety minutes, two different theories about CDN caching. Then someone ran the raw MIME source through a Base64 decoder and found the problem immediately — the backend was calling btoa() on UTF-8 strings and quietly corrupting every character outside the Latin1 range. Korean characters in usernames. Emoji in display names. All broken, silently. Understanding Base64 would have prevented this in twenty minutes of code review.

What Base64 Is (and What It Isn't)

Base64 is a binary-to-text encoding scheme that converts binary data into 64 safe ASCII characters (A-Z, a-z, 0-9, +, /). It was designed to solve one specific problem: transmitting binary data through systems that only handle 7-bit ASCII text — primarily email (SMTP), which was built in an era before binary file support.

• Takes 3 bytes (24 bits) of binary data at a time
• Splits each 3-byte chunk into 4 groups of 6 bits
• Maps each 6-bit value to one of 64 printable ASCII characters (A-Z, a-z, 0-9, +, /)
• Output is always exactly 33% larger than the original — that overhead is the cost of text-safe encoding
• If the input length isn't divisible by 3, = padding characters fill the remaining space

Where Base64 Shows Up in Real Code

Base64 isn't one thing — it appears in multiple different contexts, each with slightly different rules. Knowing which variant you're dealing with prevents hours of debugging.

• Email attachments (MIME): SMTP was designed for 7-bit ASCII text. Attaching a binary file requires Base64 encoding the content — that's what your email client does automatically when you attach a PDF.
• Data URIs in HTML/CSS: Embed small images directly in markup using data:image/png;base64,... — eliminates an HTTP request at the cost of a 33% size increase and loss of browser caching.
• API payloads (JSON): JSON is text-only, so binary data — images, audio, PDFs — must be Base64-encoded to travel inside JSON request or response bodies.
• JWT tokens: JSON Web Tokens encode the header, payload, and signature as URL-safe Base64 (base64url). That's what the three dot-separated parts of a JWT are.
• HTTP Basic Auth: The Authorization header contains username:password Base64-encoded. It's not encrypted — anyone who sees the header can decode it instantly.

Standard Base64 vs URL-Safe Base64

Mixing these up is a common bug. If you encode with standard Base64 and embed the result in a URL, the + signs get decoded as spaces and / starts a path segment. Always use URL-safe Base64 for anything that goes in a URL or an HTTP header.

The btoa() UTF-8 Problem

JavaScript's built-in btoa() function only handles Latin1 characters. Pass it a Korean character, emoji, or anything outside the 0-255 byte range, and it throws: 'The string to be encoded contains characters outside of the Latin1 range.' This is the bug in our welcome email story. The fix requires encoding to UTF-8 bytes first:

// WRONG — fails on any non-Latin1 character
btoa('안녕하세요') // throws DOMException

// CORRECT — handles full UTF-8
function base64Encode(str) {
  return btoa(
    Array.from(new TextEncoder().encode(str))
      .map(byte => String.fromCharCode(byte))
      .join('')
  );
}

function base64Decode(b64) {
  return new TextDecoder().decode(
    Uint8Array.from(atob(b64), c => c.charCodeAt(0))
  );
}

Tool Comparison: btoa() vs Terminal vs QuickFigure