How to Embed Images in HTML Email

To embed an image in HTML email, use a hosted image URL, a CID attachment referenced from the message HTML, or a Base64 data URI. Hosted URLs keep messages smaller, CID attachments bundle the image with the email, and Base64 support varies by email client.

Test the delivered message before release because Gmail, Outlook, Apple Mail, and mobile clients handle remote and embedded images differently. This guide compares attached and embedded images, explains the three methods, and shows how MailSlurp helps verify the final message.

Attached vs. embedded images

An image sent as a normal attachment appears separately from the message body and can be downloaded by the recipient. An inline image is referenced by the HTML so that it can appear as part of the message.

Inline delivery does not guarantee display. Email clients can block remote images, proxy or cache hosted files, and handle CID attachments or Base64 data differently. Use explicit image dimensions, descriptive alt text, and a layout that still works when an image is unavailable.

File attachments

Use a regular attachment when the recipient needs the original file to download rather than an image that forms part of the message design. Keep the provider's total message-size limit in mind.

Inline images

Use an inline image when the graphic belongs in the message body. Choose between a hosted URL, CID attachment, or Base64 data URI based on message size, client support, privacy requirements, and caching behavior.

There is no universal client default to rely on. Recipients can change privacy settings, and client behavior changes over time, so test the actual delivered message across the clients your audience uses.

Three ways to embed images in HTML email

Here are the three main methods for inserting images into emails.

1. CID attachments

MIME (Multipurpose Internet Mail Extensions) lets an email contain different parts, such as text, HTML and image files.

Attach the image as an inline MIME part and reference its Content-ID from the HTML. This illustrative HTML refers to an image part whose header is Content-ID: <product-image@news.example>:

<img src="cid:product-image@news.example" alt="Example product" />

The image bytes must be included in the message, and the identifier must match the delivered HTML reference. Attaching a PNG by filename alone does not establish that relationship. RFC 2392 defines how cid: references identify MIME body parts. Use a unique Content-ID for each image part.

2. Base64 data URIs

Embedding a base64 image in HTML is another method for displaying an image in the body of your message. Base64 is a collection of related binary-to-text encoding techniques.

Base64-encode the image file and place the encoded data in the image source. This increases message size and is not supported consistently, so test it with the email clients you need to support.

A PNG data URI begins with data:image/png;base64, followed by the actual encoded image bytes. A placeholder string is not a usable image. Base64 encoding used to transport a MIME attachment is different from putting a data URI inside the HTML; a CID image can use the former without using the latter.

3. Hosted image URLs

Host the image on a public HTTPS URL and reference it with an img tag. This keeps the image bytes out of the message itself, although clients may block, proxy, or cache the request.

<img src="https://example.com/email/image.jpg" alt="Example product" />

Use stable URLs and make sure the image remains available for as long as recipients may open the message.

How to test images in HTML email

Send the finished email into a MailSlurp test inbox through the provider you normally use. For an application-generated message, use the same email library and sending route as the application. The delivered MIME may differ from the HTML and attachment settings you started with.

Open the received message's HTML and attachments, then request the clients your audience uses in device previews. Inspect each completed capture for the actual logo or image, its proportions and its position. A completed capture can show a missing-image placeholder, so include the visible result in your check.

Find the image problem in the delivered email

Start with the source that actually reached the inbox. For a hosted image, check the delivered URL and whether it returns the intended file without your account's login. For a CID image, confirm that the message includes the image part and that its Content-ID matches the HTML reference.

If the attachment exists but the image is still blank, compare the delivered Content-ID and Content-Disposition with the MIME your sender created. Check how the HTML and image parts are grouped, too. Keep the received source and affected capture together when investigating; attachment presence alone does not establish that the image displayed.

Then use the visible symptom to choose the next check:

• A blank area or download notice: follow the images-not-showing guide to distinguish a blocked remote download from an unavailable image and keep the offer readable.
• A sharp image that is too wide or clips on a phone: check the email design-size guide for display dimensions and the surrounding layout.
• A logo that disappears only in dark mode: use the dark-mode preview guide to inspect contrast and background changes.
• A problem in one client only: compare that named result with the other clients your audience uses in device previews. Keep Outlook Classic and New Outlook separate.

Send the corrected campaign through the same provider and rerun the affected client. The Mailchimp rendering walkthrough and HubSpot rendering walkthrough show how to test the delivered campaign rather than relying only on the editor preview.

Check the finished campaign before sending

Choose the image method that fits your sending workflow, then check the delivered email across the clients your readers use. Include an images-blocked check where available so the message still makes sense when only the alt text and surrounding copy are visible.

Preview your delivered email to spot missing images, distorted logos and layout changes before the campaign goes out.