Inline Email Images: CID Attachments, Hosted URLs and Reliable Fallbacks

TL;DR

• Hosted images use a public HTTPS URL; CID images travel as related message attachments referenced from the HTML.
• Keep important information in text because image display varies across email clients and recipient settings.
• Test the actual message in representative clients, including with remote images disabled.
• Use trusted image sources and bounded file sizes; do not let untrusted input choose arbitrary server files or fetch URLs.

Choose the image method for the message

An HTML email can reference a hosted image or include image bytes in the message itself. The choice affects message size, caching, privacy and how the email behaves across clients.

A hosted image uses an HTTPS URL in the HTML. The recipient's client may fetch it directly, proxy it, cache it or block it until the user allows images. A CID image uses a Content-ID reference that points to a related MIME part included with the email.

Neither approach means you can ignore client testing. A design that looks correct in one webmail client may display differently in a desktop or mobile application. Keep the message understandable when the decorative image is absent.

A hosted-image example

Here is a small original HTML example:

<p>Your project summary is ready.</p>
<img
  src="https://assets.example.com/email/project-summary.png"
  width="480"
  alt="Illustration of a project checklist"
  style="display:block;max-width:100%;height:auto;"
>
<p>Sign in to your account to review the details.</p>

The domain is a placeholder. Use a stable, public asset URL that does not require a login cookie. Do not put a customer's private report or sensitive information in a publicly hosted decorative image. Avoid short-lived signed URLs for assets that readers may reopen much later.

The surrounding text carries the actual instruction, so the email still makes sense if the image is blocked. Alternative text describes the image rather than repeating a long marketing paragraph.

A CID example with Nodemailer

Nodemailer's embedded-image documentation explains the relationship between an attachment's cid and the HTML src. An original message fragment looks like this:

const message = {
  subject: "Project summary",
  text: "Your project summary is ready in your account.",
  html: '<p>Your summary is ready.</p><img src="cid:summary@example.com" alt="Project checklist">',
  attachments: [{
    filename: "summary.png",
    path: "./trusted-assets/summary.png",
    cid: "summary@example.com",
  }],
};

This fragment still needs your server-side transport, sender and controlled recipient. The CID in the HTML must match the attachment value. Use an identifier unique within the message. The image bytes increase the email's size, so resize and optimise the asset before packaging it.

Compare the tradeoffs

Do not use an image-loading event as a precise record of human reading. Proxies and privacy features can change when and how remote resources are requested. A reliable product workflow should not depend on a decorative image being fetched.

Test the complete email

Send controlled test messages using the same construction path as production. Check desktop and mobile layouts, dark mode where relevant, image-disabled behaviour and the plain-text version. Forward the message once and inspect whether the result remains understandable.

Verify links separately from image display. A beautiful header does not help if the primary action opens an expired URL. Also check that the total message size remains within your provider's documented limits after attachments and MIME encoding are included.

If an image is unexpectedly shown as an attachment, inspect the generated MIME structure and the client involved rather than changing unrelated delivery settings.

Keep attachment handling within a trusted boundary

Use application-owned assets or validated uploads. Do not accept arbitrary file paths from a request and pass them to the mail library. The same principle applies to remote URLs: an unrestricted server-side fetch can reach places the application should not access.

Nodemailer's attachment documentation describes supported attachment inputs. Choose the narrowest input type your feature needs and enforce size and content checks before building the message.

For the surrounding sending workflow, read our Node.js email guide. The image is one part of a reliable message; delivery records, useful text and tested links complete the experience.