---
title: "Library images"
description: "The images your templates embed. Upload from a URL or as base64; a template takes an image's `path` (`/img/…`). A delete is refused while something uses the image, unless you force it."
url: https://www.unitpost.com/docs/api/library-images
section: API reference
updated: 2026-10-13
---
# Library images

## Library images

> The images your templates embed. Upload from a URL or as base64; a template takes an image's `path` (`/img/…`). A delete is refused while something uses the image, unless you force it.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/platform/library-images.

## Operations

### `GET /api/v1/library-images`

List images

The workspace's image library, newest first: the images a template embeds. Each image's `path` (`/img/…`) is what a template's `<Image src>` (or `<img src>`) takes; `url` is its public address. Requires the `templates:read` capability.

Reference: https://www.unitpost.com/docs/platform/get-library-images ([Markdown](https://www.unitpost.com/docs/platform/get-library-images.md))

### `POST /api/v1/library-images`

Upload an image

Add an image to the library from a public https `url` (fetched once, no redirects, no private addresses) or base64 `data` with its `content_type`: PNG, JPEG, GIF or WebP up to 5 MB and 16,384 px a side (50 megapixels at most), counted against the plan's image storage (`403 limit_reached`). Send an `Idempotency-Key` so a retried upload stores one image. Requires the `templates:write` capability.

Reference: https://www.unitpost.com/docs/platform/post-library-images ([Markdown](https://www.unitpost.com/docs/platform/post-library-images.md))

### `GET /api/v1/library-images/{id}`

Retrieve an image

One library image. Requires the `templates:read` capability.

Reference: https://www.unitpost.com/docs/platform/get-library-images-id ([Markdown](https://www.unitpost.com/docs/platform/get-library-images-id.md))

### `PATCH /api/v1/library-images/{id}`

Update an image

Change the alt text the image suggests when it's inserted. Requires the `templates:write` capability.

Reference: https://www.unitpost.com/docs/platform/patch-library-images-id ([Markdown](https://www.unitpost.com/docs/platform/patch-library-images-id.md))

### `DELETE /api/v1/library-images/{id}`

Delete an image

Remove an image from the library. While a template, a campaign or sent mail uses it, the answer is `409 resource_in_use` naming them (`details[]`); `force=true` deletes it anyway, as the dashboard's "Delete anyway" does: those emails then show a broken image wherever it isn't cached yet. Requires the `templates:write` capability.

Reference: https://www.unitpost.com/docs/platform/delete-library-images-id ([Markdown](https://www.unitpost.com/docs/platform/delete-library-images-id.md))

## Related

- [Branding](https://www.unitpost.com/docs/api/branding): The look marketing emails' footer and the hosted unsubscribe page share, with the same options as Settings → Brand, and the logo. Writes need `branding:write`, which no key preset includes.
- [Workspace](https://www.unitpost.com/docs/api/workspace): The workspace's name and image (writes need `branding:write`), who is calling (`GET /whoami`, any credential), and the activity log (`GET /activity`, `activity:read`: no key preset includes it).
- [Segments](https://www.unitpost.com/docs/api/segments): Named groups of contacts used to target campaigns. Segments decide who a campaign goes to; topics (below) decide what recipients can opt out of.