Data URI images in email clients: what actually renders

Published 2026-11-10 · client-by-client, with a test-first workflow

Email is not the web with different fonts. On the web, a data URI in an <img src> is a browser feature with a specification behind it. In email, the same markup is handed to a receiving client that treats your HTML as untrusted input, runs it through a sanitizer, and re-renders whatever survives with its own engine. Whether a Base64 image appears is decided there, on the recipient's machine, and you never get an error back.

That is why the same template can look correct in three inboxes and blank in two. This page maps the split by client context, explains what each failure actually looks like, and gives the patterns that survive a mixed audience.

Why email sanitizers treat data URIs as hostile

A data URI carries arbitrary bytes inside an attribute. From a security standpoint that is a payload with no origin: there is no host to block, no URL to inspect, no reputation to check, and no way for a proxy to scan the content before the recipient opens the message. A tracking pixel and a hidden exploit payload look identical in transit.

So clients make a policy choice. Some pass data: through untouched. Others remove the attribute, or swap the whole src for a placeholder. The removal is silent by design — mail has no console, no network tab, and no way to surface a rendering error to the sender.

Two more layers stack on top of that. Many clients proxy remote images through their own servers, which imposes size and format limits you cannot see. And nearly all of them block remote content by default until the recipient opts in, which is a separate mechanism from data URI support and often gets confused with it. An image that fails to appear may be blocked rather than stripped; the two have different fixes.

Client by client, with honest hedges

Client behavior is not a specification and it changes between builds. The table below reflects long-standing, widely reported behavior rather than a guarantee. Treat every row as "expect this, verify with a real send."

Data URI images in email, by client context
Client contextUsually rendersCommon failure modeSafer alternative
Outlook, Windows desktop No. Message HTML is rendered by the Word engine, which has no data URI support. Blank area or a broken-image glyph where the image should be. No setting enables it. CID inline attachment, or a hosted HTTPS image.
Outlook on the web (Outlook.com, Microsoft 365) Unreliable. Received HTML goes through a sanitizer that commonly removes or replaces data: sources. Image replaced by a tiny transparent placeholder, so the layout collapses rather than showing a broken icon. Hosted HTTPS image; CID where the sending path supports MIME.
Gmail, web No. The sanitizer strips data URIs from message HTML. Silent blank space, with no fallback unless you wrote alt text. Hosted HTTPS image, or CID via an ESP that builds the MIME for you.
Gmail, mobile apps No, consistent with Gmail web — same sanitizer, same result. Blank space on a small screen, where a missing image is more noticeable. Hosted HTTPS image.
Apple Mail (macOS, iOS) Usually yes. The most permissive mainstream client for data URIs. Very large embedded strings can hit message size limits or slow rendering on older devices. Fine as-is for a known Apple audience; keep files small.
Thunderbird Usually yes, in message bodies and in signatures. Same size caveats; behavior can differ between release channels. Fine as-is, or hosted if the audience is mixed.

Two rows account for nearly all reported breakage: Outlook on Windows and Gmail. If your audience is business email, assume both are present in quantity. The permissive clients are real, but they are not the majority of a typical B2B list, and a template that only works for them is a template that fails for most recipients.

Apple Mail deserves a specific note because it produces false confidence. It renders data URIs correctly, including in signatures, so your own test message will look perfect. The people who report a blank box are on a client you are not testing with. The Outlook-specific walkthrough covers the diagnosis in detail.

The three ways an image can travel

Almost every blank-image bug comes from conflating these. They are not variations of one technique; they are different transport mechanisms with different failure profiles.

Hosted URL

<img src="https://cdn.example.com/logo.png">. The client fetches the file when the recipient allows remote images. This is the most broadly compatible option and the only one where swapping the file updates mail you already sent. Its cost is the remote request, which is also why it is subject to image blocking and why it leaks open data.

CID inline attachment

The image rides in the MIME structure as an attachment with a Content-ID, and the HTML points at it with <img src="cid:logo001">. No external request, no paperclip icon when the disposition is inline. This survives Gmail and Outlook desktop. It requires a sending path that can build MIME — an API or a mail library, not a paste-into-an-editor workflow.

Data URI

The bytes sit in the HTML attribute. Zero requests, fully self-contained, and dependent on the receiving client's goodwill. Useful for previews, for known-permissive audiences, and for generated mail that must not upload anything to a server.

The practical ordering for anything sent to unknown recipients is hosted URL first, CID second, data URI only when you know who is reading. The HTML email overview goes deeper on how each mechanism interacts with image blocking and message size.

Working patterns that survive a mixed list

If you are sending through an ESP, you almost certainly have CID available and should use it. The Base64 string goes in the attachment field, never in the src, and the HTML references it by content ID.

  • SendGrid takes raw Base64 in the attachments array with disposition: "inline" and a content_id you choose, matched exactly by cid: in the HTML. The SendGrid inline image guide has the full payload in Node, Python, and curl.
  • Postmark uses the same shape with different field names: Attachments[].Content holds raw Base64 and ContentID holds the cid: value. See the Postmark CID guide for the exact JSON.
  • Signatures are a separate problem. Gmail's signature editor caps the whole signature at roughly 10,000 characters and re-serializes what you paste, so a Base64 logo either gets dropped or truncated. The Gmail signature page walks through the upload route that actually works.

If you cannot use CID and cannot host the file, ship the image as a hosted URL and accept the remote request. What you should not do is ship a data URI as the only copy and hope. At minimum, write alt text that carries the meaning the image was supposed to carry — a large share of your audience will see exactly that.

For signatures specifically, the email signature guide covers the client split and the small-file constraints that apply when a logo is repeated on every message you send.

Test before you send, in this order

Email has no staging environment, so the test is the only verification you get. Run it in this sequence; each step catches a different class of failure.

  1. Send to yourself on the permissive client first. If it fails there, the problem is your markup or your encoding, not client policy. Check for a truncated string or a missing data: prefix before looking anywhere else.
  2. Send to a real Gmail account. Not a Gmail address forwarded elsewhere — an actual inbox in the Gmail web interface. This is where stripped data URIs become visible.
  3. Send to a real Outlook on Windows account. If nobody on your team has one, that is the gap most likely to reach a customer before you do.
  4. Open one message with images blocked. Most clients block remote content by default, so this is the state a large share of recipients see first. If the message is unreadable with images off, the design depends on something you cannot guarantee.
  5. Read the plain-text part. If you send multipart/alternative, confirm the text part makes sense on its own. Many clients fall back to it, and some corporate gateways prefer it.
  6. Check the raw source of a received copy. Look for src="data:. If it is intact in the source but invisible on screen, the client refused to render it. If it is gone, something stripped it in transit — which may be a gateway rather than the client.

Keep a small set of seed accounts across those clients and reuse them for every template change. Client behavior shifts with releases, and a test you ran last year proves nothing about this month.

When to use it, when to avoid it

A data URI is reasonable when:

  • You know the recipients use Apple Mail or Thunderbird.
  • You are building a preview or an internal test, not a production send.
  • No hosting and no attachment API are available, and zero-upload handling is the point.
  • The message must survive as a single self-contained file.

Avoid it when:

  • The list includes Gmail or Outlook addresses in any quantity.
  • The image is the message — a chart, a receipt, a product shot.
  • You are pasting into a signature editor that re-serializes HTML.
  • You need delivery guarantees you can verify after the send.

Encoding for the clients that do support it is still a legitimate need. The data URI generator produces a ready-to-paste snippet locally, so a test image never has to touch a server.