For detailed information about the infrastructure options and configuration, please refer to the section below.
### Sizing options
Once your end-users deselect “Auto width” in the image sidebar, they are presented with two sizing modes to choose.
#### Original
The image keeps its native proportions — no cropping, no fit/fill choice. This is the default for any image that hasn't been resized before, and it's the only mode compatible with Dynamic Images (see below).
#### Presets
Your end-users can crop the image by choosing from five standard ratios – Square (1:1), Portrait (4:5), Standard (4:3), Wide (16:9), Banner (2:1)
With a preset selected, your users can also choose **Fit** or **Fill**. The former scales the image so it's fully visible inside the frame, without cropping anything out; the latter scales the image so it completely covers the frame, cropping any excess. Fill is the default the first time you select a preset.
When Fill is selected, a 9-point grid lets you choose which part of the image stays in frame when it's cropped — useful when the subject isn't centered in the original photo.
If your end-users remove an image and add a new one in its place, existing layout settings — ratio, fit/fill, focal point, alignment — carry over automatically.
#### Mobile
Sizing and cropping settings are shared between desktop and mobile, with one dedicated mobile option: **Full width on mobile**, available for both Original and every preset.
Mobile images are regenerated from the original file, so they stay sharp on retina screens instead of looking blurry. When Full width on mobile is on, the separate mobile-width slider is disabled, since it wouldn't have any visible effect.
#### Working with Dynamic Images
[Dynamic Images](https://docs.beefree.io/beefree-sdk/resources/cookbook/use-dynamic-images-for-email-personalization) only work with the **Original** ratio. The reason is that the real image's dimensions aren't known until the merge tag is resolved, so forcing it into a fixed preset ratio ahead of time could distort or stretch the final image.
#### Supported file types
JPEG, PNG, GIF and WebP are supported and tested. Animated GIFs are capped at 100 frames.
### Advanced Permissions
Advanced Permissions let you control which Image block settings your end-users can see or change. For example, you can hide the entire Advanced Image Layout block from a given user role.
Advanced Image Layout’s controls don't get permissions of their own. They're governed by the existing `ImageWidth` permission, which today controls show/lock behavior for the original width slider.
### What happens when Advanced Image Layout is unavailable
Once an image has been edited with Advanced Settings, the controls stay visible and fully usable in the sidebar for end-users, even after the feature is disabled in the SDK console or restricted via Advanced Permissions.
A common use case entails the [Template Catalog](https://docs.beefree.io/beefree-sdk/apis/template-catalog-api#overview-of-template-catalog-api): if a designer builds a template using Advanced Image Layout and distributes it via the Template Catalog, any user downloading it - even with the feature disabled - will be able to use the Advanced controls on that specific image.
If the ratio is switched back to **Original**, the underlying settings aren't deleted — they're cleared, but a flag (invisible to the end-user) stays in place recording that this specific image was edited with Advanced Settings at some point. That flag is what keeps the controls recoverable.
### Cost & data allotment
Every export generates a fresh, signed transform URL for whichever CDN is configured at that moment — nothing is created or stored per image in advance. This has two consequences: first, switching your CDN setting affects every export from that point forward, including re-exports of existing templates. Re-export a template after switching CDN, and it picks up fresh URLs on the new CDN — the template itself isn't locked to whatever CDN was active when it was first built.
Secondly, already-sent emails **keep the URLs they were exported with**. Signed URLs never expire, so an email exported while Beefree SDK's CDN was configured keeps counting toward your data allotment indefinitely — even after you disable the feature or switch to a custom CDN. There's no way to retroactively move or re-serve a URL that's already gone out.
Whether a given export counts toward your allotment also depends on the image's aspect ratio setting at export time:
* If you're on **custom storage** and haven't configured a dedicated CDN route for Advanced Image Layout, exporting with Original selected (instead of a preset) uses the image's original URL, keeping it on your own CDN instead of Beefree's.
* If you're on **default** (Beefree-hosted) **storage**, none of this changes your CDN costs — you're billed for CDN traffic the same way whether or not Advanced Image Layout is active. The ratio distinction above only matters for custom storage.
{% hint style="info" %}
**Existing images keep their capabilities**: Image blocks already edited with Advanced Image Layout keep their layout controls and keep counting toward your data allotment — served by Beefree SDK's CDN — until an end-user removes them. This applies whether the feature was later disabled in the console, or a template containing these images is opened without the feature enabled and the related custom CDN settings configured.
{% endhint %}
### Image sidebar update
With the release of Advanced Image Layout (Beefree SDK 3.56), we took the chance to improve the Image block sidebar for all end users, regardless of Advance Image Layout’s activation. It now follows a natural, top-to-bottom flow that mirrors how users actually build:
1. **Image Source** — add or replace the image. This is the entry point: it's what unlocks the widgets below.
2. **Dynamic Image** — the alternate, merge-tag-driven source, positioned right under Image Source since it replaces the placeholder set there.
3. **Image Dimension** — sizing, ratio, fit, and crop controls, grouped together as the final step.
| Old | New |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 
| 
|
A couple of small naming changes come along with this: Choose image has been replaced with Add Image; Change image is now Replace.
Two things stand out with the new order. Image Source now stays right at the top, no matter how many sizing options Image Dimension grows to include. Placing Dynamic Image right next to the aspect-ratio control makes the relationship between the two immediately visible.
This Image sidebar improvement ships for every builder, regardless of whether you activated Advanced Image Layout.
### CDN Configuration
Advanced Image Layout produces a real image file for each transformation, and that file has to be hosted somewhere it can be loaded from when the email, landing page, or popup is opened.
If Beefree SDK [stores and serves your images](http://docs.beefree.io/beefree-sdk/file-manager/cdn-domains), transformed images are delivered from the same segmented CDN domain that already serves the rest of your assets. There's nothing to configure and no new domains to allowlist. If you're unsure whether you're on a custom CDN, open your application in the [Developer Console](https://developers.beefree.io/login), go to Configure Application > Storage options, and check the CDN domains listed there. If you see “Use the default storage” option selected then there’s nothing additional you need to configure.
{% hint style="info" %}
**How usage is tracked**
If you've set up your own CDN, every cache miss triggers a call to Beefree SDK's Content Services API, which counts toward your data allotment. Subsequent renders of the same image are served from your CDN's cache and don't generate additional calls, which is why caching correctly (see [Caching is an operating requirement](#caching-is-an-operating-requirement) below) keeps your usage proportional to unique images rather than total opens. If you're on default (Beefree-hosted) storage, this tracking doesn't apply — the equivalent lookup happens entirely within Beefree SDK's own infrastructure.
{% endhint %}
### Who needs this
Custom storage works with Advanced Image Layout. It just takes more setup than default storage: you need to configure a transform route so your images can be served from your own CDN. Beefree SDK can't serve transformed images from infrastructure it doesn't own, so without this route there's nowhere for the transformed image to come from.
If you’d rather not configure a CDN, you have two other options:
* Route through Beefree SDK’s CDN instead. Available on opt-in for custom storage, this takes less setup, but your transformed images are then served from Beefree SDK infrastructure rather than your own. This matters if you chose custom storage for data-residency or compliance reasons.
* Don't enable Advanced Image Layout. Your end users stay on Original sizing, which is today's proportional-scaling behavior. Crop, fit, fill, and focal point options won’t be available.
There's no automatic fallback. Beefree SDK won't serve your transformed images without your explicit opt-in, so if you don't configure the route, your end users won't get the Advanced Image Layout controls.
### How it works
With Advanced Image Layout enabled, exported HTML embeds signed image URLs pointing at Beefree SDK's CDN. Once you set a base URL and path prefix in the Developer Console, those URLs point at your domain instead:
```html
https://| # | Requirement | Value |
|---|---|---|
| 1 | Serve your chosen hostname over HTTPS | For example images.example.com, with a valid TLS certificate |
| 2 | Route the prefix to the Beefree SDK origin | /<your-prefix>/* → api.getbee.io |
| 3 | Prepend the origin base path | Origin path /v1/transform. CDNs prepend rather than rewrite, and the endpoint ignores the prefix segment in between, so you don't need rewrite rules |
| 4 | Add the auth header on origin requests | Authorization: Bearer <your-api-key>, set as an origin or custom header |
| 5 | Cache, honoring the origin Cache-Control | Successful responses carry Cache-Control: public, max-age=86400. Error responses are no-store and must not be cached. |
.png?alt=media&token=91470e45-4424-4291-a800-a5c561101ef6)
* **Base url** is your hostname, for example `https://images.example.com`. HTTPS is required.
* **Path prefix** is the prefix you routed, for example `edited-images`. Slashes around it are normalized either way.
The change takes effect immediately in the editor, for both preview and editor-side export. HTML exports through the Content Services API pick it up within one hour, because the API caches each application's serving configuration for that long. Switching back to Beefree SDK's CDN behaves the same way.
### Caching is an operating requirement
{% hint style="warning" %}
**Important:** Your CDN must cache transformed images. `/v1/transform` is rate-limited per application because it's an API entry point, not a content-delivery service. Cached correctly, the limit never comes into play, since each unique URL reaches Beefree SDK at most once a day. Uncached, every email open goes straight to the API, exhausts the limit, and recipients see broken images.
{% endhint %}
### Verifying your setup
You can test your CDN before changing the Developer Console. Take a transformed URL from an export that used the default CDN, then swap the host and prefix for your own:
{% code overflow="wrap" %}
```shellscript
curl -sv "https://images.example.com/