Gmail Blocks Base64 Images: Convert to Blob for Inline Email

Introduction

Embedding images directly into HTML emails using Base64 data URIs is a tempting shortcut for developers who want to avoid hosting files externally. Unfortunately, Gmail – the most widely used email client – deliberately strips out these Base64 strings, causing the images to disappear for the recipient. Google Apps Script (GAS) offers a workaround: by converting the Base64 string into a Blob object, you can attach the image as an inline resource that Gmail will render correctly. In this article we will explore why Gmail blocks Base64 images, how to transform a Base64 string into a Blob, the exact steps to compose an email with inline images using GmailApp.sendEmail, and a complete, ready‑to‑run script example. By the end, you’ll have a reliable method for sending rich, image‑filled emails from your Google Workspace environment.

Why Gmail Blocks Base64 Images in HTML Emails

Gmail’s security team disables Base64‑encoded images for several reasons:

• Performance: Large data URIs increase the size of the email payload, slowing down loading times for both the sender’s server and the recipient’s inbox.
• Phishing protection: Inline data can be used to hide malicious content that would otherwise be scanned when fetched from an external source.
• Consistency: Rendering engines differ across platforms; stripping Base64 ensures a uniform experience for all Gmail users.

Because of these policies, any src="data:image/...;base64,..." attribute is stripped during the sending process, leaving a broken image placeholder. To bypass this, the image must be attached as a separate MIME part and referenced with a cid: (Content‑ID) link, which Gmail fully supports.

Converting Base64 Strings to Blob Objects in Apps Script

Google Apps Script provides the Utilities.base64Decode() method, which converts a Base64 string into a byte array. This array can then be wrapped in a Blob using Utilities.newBlob(). The key steps are:

• Remove the data‑URI prefix (e.g., data:image/png;base64,) to isolate the raw Base64 data.
• Decode the string with Utilities.base64Decode().
• Create a Blob, specifying the MIME type and an optional filename.

Example code snippet:

var raw = base64String.replace(/^data:image\/\w+;base64,/, “”);
var bytes = Utilities.base64Decode(raw);
var blob = Utilities.newBlob(bytes, “image/png”, “photo.png”);

This Blob can now be attached to an email and referenced with a Content‑ID, allowing Gmail to render it inline.

Composing an Email with Inline Images Using GmailApp.sendEmail

The GmailApp.sendEmail() function accepts an options object where you can define htmlBody, inlineImages, and other parameters. The inlineImages property expects a map of cid names to Blob objects. In the HTML body, you reference the image with <img src="cid:myImage">. The workflow looks like this:

• Prepare the HTML body and insert a cid placeholder where the image should appear.
• Build an object, e.g., {myImage: blob}, and pass it as inlineImages.
• Call GmailApp.sendEmail(recipient, subject, plainText, options) where options.htmlBody contains the HTML with the cid reference.

This method guarantees that Gmail treats the image as an attachment with a Content‑ID, rendering it correctly for every recipient.

Full Script Example and Testing Steps

Below is a complete, functional script you can copy into the Apps Script editor. It reads a Base64 string, converts it to a Blob, and sends an email with the image displayed inline.

function sendBase64ImageEmail() {
  var recipient = “[email protected]”;
  var subject = “Test Email with Inline Base64 Image”;
  var base64 = “data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…”; // truncated
  // Strip prefix and decode
  var clean = base64.replace(/^data:image\\/\\w+;base64,/, “”);
  var bytes = Utilities.base64Decode(clean);
  var imgBlob = Utilities.newBlob(bytes, “image/png”, “logo.png”);
  var html = ‘<p>Hello,</p>’ +
    ‘<p>Here is the image you requested:</p>’ +
    ‘<img src=”cid:logoImg” alt=”Logo”>’;
  var options = {
    htmlBody: html,
    inlineImages: {logoImg: imgBlob}
  };
  GmailApp.sendEmail(recipient, subject, “Your email client does not support HTML.”, options);
}

Testing steps:

• Paste the script into a new Google Apps Script project.
• Replace the recipient and base64 variables with real values.
• Run sendBase64ImageEmail() and authorize the required scopes.
• Open the received email in Gmail; the image should appear exactly where the <img> tag is placed.

Tips, Common Pitfalls, and Troubleshooting

Even with the correct approach, you might encounter hiccups. Keep these pointers in mind:

• Correct MIME type: Ensure the Blob’s MIME type matches the original image format (e.g., image/jpeg for JPG files). Mismatched types can cause Gmail to display a broken image.
• Unique CID names: If you send multiple images, give each a distinct CID (e.g., cid:image1, cid:image2) and map them accordingly in inlineImages.
• Size limits: Gmail imposes a 25 MB total attachment limit. Large Base64 strings can quickly exceed this, so consider resizing or compressing images before encoding.
• Testing in other clients: While Gmail handles inline images flawlessly, some third‑party clients may treat them differently. Always test across a few platforms if your audience uses diverse email apps.
• Debugging: If the image does not appear, check the raw email source (via Gmail’s “Show original”) to verify that a Content‑ID header is present and that the cid reference matches exactly.

Conclusion

Gmail’s refusal to render Base64 data URIs can be frustrating, but Google Apps Script turns this limitation into an opportunity by letting you convert Base64 strings into Blob objects and attach them as inline images. By understanding why Gmail blocks raw Base64, mastering the conversion to Blob, and using GmailApp.sendEmail with the inlineImages option, you gain full control over the visual appearance of your automated emails. The provided script demonstrates a practical, repeatable workflow that works reliably for any image format supported by Gmail. Apply the tips and troubleshooting advice to avoid common mistakes, and you’ll be able to send polished, image‑rich messages directly from your Google Workspace environment with confidence.