Media library

Images, PDFs and zips, uploaded once and referenced from any email — with the alt text an image carries wherever it's inserted.

The media library lives under Content → Media. Everything in it is hosted at a stable URL, and email content references that URL: images render inline, PDFs and zips are linked for the reader to download. One upload can be referenced from as many emails as you like.

Storage comes first

Uploads live in your own storage, not inside Mimeo's database. Until a storage backend — Cloudflare R2, Amazon S3, or the built-in local hosting — is chosen under Settings → General → Storage & media, the media library is read-only: a notice links you to the setting, existing items stay viewable and insertable, and the upload button appears once storage is set.

Storage itself waits on one thing before it: a connected domain and a sender. Media serves from a subdomain of a domain you send from, so there is nothing to point it at until one exists.

Why the host matters

Every upload's URL is frozen into each email that references it. Already-sent mail can never be repointed at a new host, so the domain files serve from is a decision you make once and live with.

That is why R2 media rides a subdomain of your own sending domain rather than R2's shared r2.dev host, which is rate-limited and shared with every other Cloudflare customer. On S3 the bucket's own URL is already yours alone, so it needs no domain at all.

Setting up the host

On Cloudflare R2, choose a subdomain (files is the usual pick) and the domain beside it, then connect that host to your bucket in Cloudflare → R2 → your bucket → Settings → Custom domains. Cloudflare adds the DNS record itself, so there is nothing to set at your registrar — but the domain's DNS has to be on Cloudflare for R2 to serve it.

R2's credentials come from an API token. Under Cloudflare → R2 → API → Manage API tokens, create a token with Object Read & Write permission limited to your bucket. The creation screen shows its Access Key ID and Secret Access Key exactly once — those two values, plus the account ID from the R2 overview page and the bucket name, are everything the storage form asks for. Losing the pair is no crisis: create a new token and save its values instead.

On Amazon S3 there is no host to set up. Files serve from the bucket's own URL, built from the region and bucket name. The bucket does have to allow public reads: turn off Block Public Access and add a bucket policy granting s3:GetObject to everyone. Credentials are an IAM access key pair with write access to the bucket, created under IAM → Users → your user → Security credentials in the AWS console.

Either way, Check media hosting proves it works. It uploads a small test file, loads it back over the public host and deletes it — so a host that resolves but doesn't serve is caught here rather than in a subscriber's inbox. A failure names the step that broke: DNS not resolving, a certificate still issuing, public access switched off, or a domain pointed at the wrong bucket.

What's accepted, and the ceilings:

Two views

The library shows as a thumbnail grid or a list — the toggle sits beside the search box, and the choice is remembered by your browser. Search matches file names and alt text.

The detail view

Click any item to open it: the full-size image (or a link to open a PDF or zip), its file name, content type and size, and — for images — the natural pixel dimensions. This is also where an image's alt text lives: write what the image shows, and every insert of that image from the library carries it. Inboxes with images off, screen readers and clipped emails all read the alt text, so it's worth the sentence.

The detail view also shows the item's hosted URL — the address the file serves from — with a copy button beside it, and the list view carries the same copy button next to each file name. Paste that URL anywhere email content is written: an email body, a component, a template, a link.

Inserting into an email

In any email editor, the Insert menu (or typing / in the body) offers From media library…. Pick an item:

• Images drop in inline, carrying their saved alt text.
• PDFs and zips insert a link to the hosted file, with the file name as the link text — edit the text like any other link. Files are linked, not attached: the email stays light and deliverability stays clean.

Deleting

Deleting an item from its detail view removes the stored file for good — after a confirmation that spells out the catch: emails already sent keep referencing the URL, so the image or download link in those inboxes stops working. Delete what nothing should point at any more; when in doubt, leave it.

In your manager repo

The library syncs into your manager repo alongside the definitions: mimeo pull downloads the files into media/ and writes media.yml — each item's hosted URL, alt text and id. Drop a new file into media/ and mimeo push uploads it; edit alt text in media.yml and push that too. A push never deletes remote media — deleting stays an explicit act here or over the API — so a file removed locally simply comes back on the next pull. Details in the CLI docs.