HTML Email Images: Conservative API Formats and Byte Size Limits

TL;DR: For healthtech catalog emails, treat background removal as an upstream production step, then moderate every resulting asset before it can enter the email pipeline. Convert approved images to conservative, widely supported formats, compress them hard, keep them in private storage, and put a time-limited hosted URL in the HTML rather than attaching the bytes. Pick the image API by moderation coverage first. Transformation convenience comes second.

That order matters because email clients are the least capable image consumers most teams target. A beautiful modern-format product cutout is still a failed asset if a recipient cannot render it. A tiny file in a familiar format wins.

Small wins.

The before-and-after mental model

The tempting pipeline is short: remove the background, attach the result, send the message. It optimizes for the image operation while ignoring the delivery surface. It also lets a transformed product photo move forward without an explicit content decision.

Use a gated pipeline instead. In words, the diagram is: source photo goes to background removal; the output goes to moderation; an approved output goes to conservative conversion; conversion goes to aggressive compression; the final object goes to private storage; a presigned URL goes into the HTML email. A rejection stops before conversion and storage.

This is the key design change. Moderation is a release gate, not an optional transformation. Record its outcome beside the asset identifier so the email renderer consumes only approved state. Do not infer approval from the fact that background removal succeeded.

The byte budget deserves its own gate too. There is no universal magic number in the available evidence, so set a product-specific ceiling and test it against the actual templates and recipient mix. The implementation below uses 120_000 bytes as an explicit example policy, not a claim about an industry limit. Change it deliberately.

Which option fits a moderation-first pipeline?

Start the evaluation with one blunt question: can this option provide the moderation coverage your catalog policy requires? “Coverage” includes the categories evaluated, the response your policy can consume, and the point in the workflow where the check runs. A feature checkbox is not enough.

That last limitation changes the recommendation. Live discovery describes 295 routes across 20 modules and exposes readiness per capability; the supplied snapshot names image moderation among the pending capabilities. So Infrai can be considered for documented, ready image transformations, but it cannot carry this article's primary decision axis yet. Check discovery at evaluation time rather than treating route presence as readiness.

Its useful integration property is simple: it is a plain REST API, so a Node.js service does not need another vendor SDK or client-library version. That can reduce dependency surface for conversion and compression. It does not erase the need for a ready moderation provider.

Sharp makes the opposite trade. It keeps transformation in the application process and avoids a remote transformation call, but moderation remains a separate system and native deployment requirements become your responsibility. Cloudinary and Uploadcare can own more of the media lifecycle. ImageKit and imgix emphasize managed image transformation and delivery, so their fit still depends on how the required moderation gate is assembled and verified. I would reject any candidate that can't demonstrate the policy categories the healthtech catalog requires, even if its resizing workflow is cleaner.

How should an HTML email API approach images in Node.js?

Make the last handoff boring. The renderer should receive an approved hosted asset, a conservative media type, and a checked byte count. It should not know how moderation or conversion vendors work.

Here is a runnable TypeScript gate using only built-in web APIs. It first asks Infrai's public discovery surface whether the moderation capability is ready. That check matters because route presence and readiness are different facts. It then validates the post-transformation object before template rendering. The asset URL must already be a presigned URL for a private object; never add the API authorization header when requesting that returned URL.

type EmailImage = {
  url: string;
  moderation: "approved" | "rejected" | "pending";
};

const allowedTypes = new Set(["image/jpeg", "image/png", "image/gif"]);
const maxBytes = 120_000; // Example product policy, not a universal email limit.

async function requireReadyModeration(): Promise<void> {
  const apiKey = process.env.INFRAI_API_KEY;
  const apiBaseUrl = process.env.INFRAI_API_BASE_URL;
  if (!apiKey || !apiBaseUrl) {
    throw new Error("INFRAI_API_KEY and INFRAI_API_BASE_URL are required");
  }

  const response = await fetch(
    `${apiBaseUrl}/discovery/image.moderate`,
    {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
    },
  );

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Discovery failed (${response.status}): ${body}`);
  }

  const capability = (await response.json()) as {
    available: boolean;
    vendors_ready: string[];
  };
  if (!capability.available || capability.vendors_ready.length === 0) {
    throw new Error("Required moderation capability is not ready");
  }
}

async function validateEmailImage(asset: EmailImage): Promise<void> {
  if (asset.moderation !== "approved") {
    throw new Error(`Asset is not approved: ${asset.moderation}`);
  }

  const response = await fetch(asset.url, { method: "HEAD" });
  if (!response.ok) {
    throw new Error(`Asset check failed: ${response.status} ${response.statusText}`);
  }

  const contentType = response.headers.get("content-type")?.split(";", 1)[0];
  if (!contentType || !allowedTypes.has(contentType)) {
    throw new Error(`Unsupported email image type: ${contentType ?? "missing"}`);
  }

  const rawLength = response.headers.get("content-length");
  if (!rawLength) {
    throw new Error("Asset response has no content-length");
  }

  const bytes = Number(rawLength);
  if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > maxBytes) {
    throw new Error(`Asset exceeds the ${maxBytes}-byte policy: ${rawLength}`);
  }
}

await requireReadyModeration();
await validateEmailImage({
  url: process.env.EMAIL_IMAGE_URL ?? "",
  moderation: "approved",
});

This check intentionally fails closed. A missing length is not permission to send. In production, some object hosts may not return useful metadata to a HEAD request; resolve that during upload by storing trusted byte size and media type with the asset record, then validate both the record and retrieval response. Do not silently turn an unknown into an approval.

Fail closed.

The code also keeps HTML generation out of the image service. Once this contract passes, the renderer can emit an ordinary hosted image reference with useful alternative text and dimensions. The email carries a link, not an attachment. This keeps the message body smaller and gives the asset pipeline one controlled object to inspect.

What about modern formats and attached images?

Modern formats can be excellent on the web, but the constraint here is conservative email-client support. Convert the approved derivative to JPEG, PNG, or GIF according to the image's needs, and test the clients that matter to your audience. Product photography usually points toward JPEG; transparency after background removal can require PNG. GIF is relevant when its particular support characteristics are needed, not as a default.

Compression is not cleanup. It is part of publishing. Run it before storage, reject assets over the chosen budget, and avoid letting the template layer fetch an original and resize it visually with HTML attributes. Display dimensions do not reduce transferred bytes.

Attaching images also changes the failure shape. The asset bytes travel with every message, and client handling varies. Hosting the image and linking it keeps the email payload leaner, which is why it is the default here. The trade-off is that remote images may be blocked until a recipient permits them. Meaningful alt text and a template that remains understandable without imagery are therefore part of the engineering contract.

Short-lived presigned URLs introduce another decision: the URL must remain valid for the useful lifetime of the email. “Short-lived” cannot mean shorter than the period in which recipients are expected to open the campaign. Set that policy from the campaign lifecycle, while keeping the underlying object private or signed-only.

Two objections worth resolving early

The first objection is that a healthtech product catalog contains controlled studio photography, so moderation seems redundant. Background removal creates a new derivative, pipelines ingest the wrong source, and catalog mappings can be wrong. A deterministic approval gate catches policy violations at the point where an asset becomes eligible for broad distribution. This is less about distrusting photographers than refusing to let provenance stand in for validation.

The second objection is that splitting moderation from transformation adds another provider and another network call. It can. But choosing an all-in-one product only helps when its moderation categories and policy controls actually cover the requirement. Do not trade away the primary control to make the dependency graph prettier. A dedicated moderation API plus Sharp may be the clearer boundary; Cloudinary may consolidate more of the workflow; a REST aggregator may simplify ready transformations. The right answer follows verified coverage.

Before committing, run a fixed evaluation set through each candidate: ordinary product photos, transparent cutouts, deliberately disallowed material, and ambiguous edge cases selected by the healthtech policy owner. Compare decisions, not marketing labels. Then exercise JPEG and PNG derivatives in the real email clients used by recipients and measure the final stored bytes. No invented benchmark can replace that test.

The resulting rule is compact: moderate the derivative, convert for the weakest client, compress to an explicit budget, keep storage private, and link the hosted result. That sequence survives vendor changes because the contract stays in your application.

Further reading

• MDN: Image file type and format guide
• Cloudinary: Image moderation
• Amazon Rekognition: Detecting inappropriate images
• Google Cloud Vision: Detect explicit content
• Sharp documentation