> ## Documentation Index
> Fetch the complete documentation index at: https://help.emaillove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Hosting

> How image hosting works on export: the Email Love CDN, bringing your own storage (S3, R2, GCS, and more), format and size best practices, and troubleshooting

When you export an email from the Email Love Figma Plugin, your images are automatically uploaded to our global CDN (Content Delivery Network) and linked in the exported HTML. This means you don't need to manually upload images to your ESP or manage a separate image library. The plugin handles it as part of the export workflow.

This guide covers how the hosting works, image format and size recommendations, and what to do when things go wrong.

## How It Works

1. Design your email in Figma with images placed in mj-image frames
2. Click **Export** in the Email Love plugin
3. Choose your export method (ESP integration, HTML download, or code copy)
4. Make sure **"Upload images to Email Love servers"** is enabled (this is on by default)
5. The plugin uploads all images to the Email Love CDN and inserts the hosted URLs into your exported code

After export, your HTML will reference images like this:

```html theme={null}
<img src="https://emaillove-assets-cdn.com/[unique-id]/image.png" />
```

If you see `emaillove-assets-cdn.com` in the URL, the image is hosted on our CDN.

## Image Format Recommendations

The format you use for each image affects file size, quality, and email client compatibility:

| Format | Best For                                 | Notes                                                                                     |
| ------ | ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| JPG    | Photos, hero images, product shots       | Smallest file size for photographic images. Use quality 70–80% for a good balance         |
| PNG    | Logos, icons, graphics with transparency | Supports transparency. Larger file size than JPG for photos                               |
| GIF    | Simple animations, animated banners      | Supported everywhere, but Outlook shows only the first frame. See the Animated GIFs guide |

<Warning>
  **Avoid WebP and SVG.** While modern web browsers support both formats, most email clients do not render them reliably. Stick with JPG, PNG, and GIF for email.
</Warning>

## Image Size Best Practices

Image file size directly affects email load time and deliverability. Large images slow down rendering (especially on mobile) and can trigger spam filters if the total email size gets too large.

**Recommended limits:**

* **Individual images:** Keep each image under **200KB** when possible
* **Total email size:** Aim for under **800KB** total (images + HTML). Gmail clips emails over 102KB of HTML, but image weight matters for load performance
* **Hero images:** These tend to be the largest. Aim for under **250KB** for a full-width hero

**Image dimensions:**

* **Full-width images:** Export at **1280px wide** (2x your 640px email width) for retina/high-DPI displays
* **Half-width images** (2-column layout): Export at **640px wide** (2x the 320px column)
* **Thumbnails and icons:** Export at **2x** the display size for sharpness on high-resolution screens

<Note>
  **Why 2x?** Most modern phones and laptops have high-resolution (retina) displays. If you export images at 1x, they'll appear blurry on these devices. Exporting at 2x ensures crisp images everywhere, and the plugin handles the HTML sizing so the image displays at the correct dimensions.
</Note>

To export at 2x in Figma, select the image frame and check the export settings in the right panel. Set the multiplier to **2x** before exporting from the Email Love plugin.

## Export Methods and Image Hosting

### ESP Integrations (Braze, Klaviyo, HubSpot, etc.)

When exporting directly to an ESP, images are automatically hosted on the Email Love CDN by default. The hosted URLs are embedded in the code that gets pushed to your ESP. No extra steps needed.

### HTML or MJML Download

When downloading HTML or copying code:

* **With image hosting enabled (default):** Images are uploaded to the Email Love CDN and URLs are embedded in the code
* **Without image hosting:** Images export as a zip file alongside the HTML. You'll need to upload them to your own hosting or ESP image library manually

### Special Case: Loops

The Loops integration works differently. Images must be exported as a zip file alongside the MJML code, then uploaded to Loops together. Loops hosts the images on its own servers. This is a Loops-specific requirement.

## Bring Your Own Image Hosting (Custom Providers)

Prefer to serve email images from your own storage and domain? You can connect your own hosting provider and the plugin will upload export images there instead of the Email Love CDN. Your exported HTML then references your URLs, which is useful for brand or compliance requirements and for keeping all image assets in infrastructure you control.

Supported providers:

* Amazon S3
* Cloudflare R2
* Google Cloud Storage
* Backblaze B2
* DigitalOcean Spaces
* Wasabi
* Vultr Object Storage
* Tencent Cloud COS

### Setting Up a Custom Provider

<Steps>
  <Step title="Open the export settings">
    Click the blue **Export** button in the plugin and open the export settings for your chosen destination.
  </Step>

  <Step title="Add a Custom Provider">
    In the image hosting options, choose to add a **Custom Provider**. The **Add Custom Provider** dialog opens.
  </Step>

  <Step title="Fill in the connection details">
    * **Storage type**: pick your provider from the dropdown (Amazon S3 is the default).
    * **Access Key**: the access key ID from your provider (for S3 this starts with `AKIA...`).
    * **Secret Key**: the matching secret. This is kept private and stored encrypted; it never ships inside the plugin.
    * **Region**: your bucket's region, for example `us-east-1`.
    * **Bucket name**: the bucket (or container) images should be uploaded to.
    * **Public web address**: the address images load from in the email, either your bucket's public URL or the CDN domain in front of it, starting with `https://`.
  </Step>

  <Step title="Test the connection">
    Click **Test connection**. The plugin uploads a small test object to confirm your credentials and bucket work before anything is saved.
  </Step>

  <Step title="Save">
    Once the test passes, click **Save**. The connection applies account-wide, so every export from your account now uploads images to your storage.
  </Step>
</Steps>

You can switch back to Email Love hosting at any time from the image hosting options.

<Note>
  🔐 Best practice: create a dedicated access key for the plugin that only has write access to this one bucket, rather than reusing a broad admin key.
</Note>

<Tip>
  Make sure your bucket allows public read access (or sits behind a CDN that does). Email clients load images directly from the URLs in your HTML, so images that require authentication will appear broken for subscribers.
</Tip>

## Using External Image URLs

If you need to reference an image hosted elsewhere (your own CDN, a dynamic image service, or a countdown timer), you can paste an external URL directly in the plugin's Properties tab instead of using an uploaded image. This is covered in detail in the **Loading External Images** guide.

This is useful for:

* Dynamic or personalized images that change per recipient
* Countdown timers and live content
* Images already hosted on your company's CDN

## What to Know About Hosted Images

**No browsable library.** Unlike traditional email builders, Email Love doesn't provide a centralized image library where you can browse all uploaded images. Your images live in your Figma files. The CDN simply hosts them for email delivery.

**Images are tied to exports.** Each time you export, the plugin uploads the current versions of your images. If you update an image in Figma and re-export, a new hosted URL is generated.

**CDN performance.** Images are served through a global CDN, so they load quickly regardless of where your subscribers are located.

**Per-license hosting.** Each license gets its own dedicated CDN pull zone, so your workspace's hosted images are isolated from other accounts rather than sharing a single common zone. This happens automatically. There's nothing to configure.

## Troubleshooting

**Images appear broken in the exported email**

Check that image hosting was enabled during export. If you exported without hosting, the HTML references local file paths that won't work in an email client. Re-export with the "Upload images to Email Love servers" option enabled.

**Images load slowly for subscribers**

Large file sizes are the most common cause. Check your image dimensions and file sizes. Full-width images should be under 250KB, and the total email should stay under 800KB. Re-export images at a lower quality setting in Figma if needed.

**Export fails or times out during image upload**

This can happen with very large images or an unstable internet connection. Try reducing image dimensions or quality, then export again. If the issue persists, check your internet connection or contact [support@emaillove.com](mailto:support@emaillove.com).

**Wrong image appears in the email**

Make sure the correct image is placed in the mj-image frame in Figma. The plugin uploads whatever image is currently visible in the frame at the time of export. If you recently swapped an image, re-export to update the hosted version.

**Images look blurry on mobile**

You're likely exporting at 1x resolution. Export images at 2x their display dimensions for retina sharpness. A 640px-wide email image should be exported as a 1280px-wide file.

**Need to find the URL of a previously hosted image?**

Open the exported HTML code and search for `emaillove-assets-cdn.com`. Each image's hosted URL is in the `src` attribute of its `<img>` tag.

## Next Steps

* **Working with images?** See [Adding Images to an Email](/plugin/images/add-images) for the basics of placing and sizing images.
* **Using external images?** Check out [Loading External Images](/plugin/images/external-images) for dynamic and externally-hosted image workflows.
* **Optimizing for mobile?** The [Mobile Optimization](/plugin/mobile/overview) guide covers responsive image behavior.
* **Ready to export?** Head to the [Export Overview](/plugin/export/overview) for a complete walkthrough of the export process.

*Need help? Reach out at [support@emaillove.com](mailto:support@emaillove.com) or join our Discord community.*