Library images

List images

GET/api/v1/library-images

GET /library-images

curl -X GET 'https://www.unitpost.com/api/v1/library-images' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Response · 200

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "library_image",
      "id": "id_123",
      "path": "string",
      "url": "https://example.com",
      "filename": "string",
      "content_type": "string",
      "size": 1,
      "width": 0,
      "height": 0,
      "alt": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

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.

Parameters3 fields

Field	Type	Description
`limit`	integer · query	Max rows to return (default 20, max 100).
`after`	string · query	Return rows after this id (forward paging).
`before`	string · query	Return rows before this id (backward paging).

Response · 200 fields12 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`path`required	string	Put this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
`url`required	string	The image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
`filename`required	string	—
`content_type`required	string	—
`size`required	integer	Bytes.
`width`required	integer \| null	—
`height`required	integer \| null	—
`alt`required	string \| null	The alt text suggested when the image is inserted.
`created_at`required	string	—
`updated_at`required	string	—

200401403422

Upload an image

POST/api/v1/library-images

POST /library-images

curl -X POST 'https://www.unitpost.com/api/v1/library-images' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'

Response · 201

{
  "object": "library_image",
  "id": "id_123",
  "path": "string",
  "url": "https://example.com",
  "filename": "string",
  "content_type": "string",
  "size": 1,
  "width": 0,
  "height": 0,
  "alt": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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.

Parameters1 field

Field	Type	Description
`Idempotency-Key`	string · header	Any unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.

Request body5 fields

Field	Type	Description
`url`	string	A public https image to fetch (no redirects, no private addresses). PNG, JPEG, GIF or WebP, up to 5 MB and 16,384 px a side (50 megapixels at most); anything else is a 422 naming `url`.
`data`	string	The image bytes, base64 (no `data:` prefix). Base64 adds a third, and a request over ~6 MB is refused before it arrives, so this fits about 4 MB of image; send larger images (up to 5 MB) by `url`. At most 16,384 px a side and 50 megapixels; anything else is a 422 naming `data`.
`content_type`	enumimage/png \| image/jpeg \| image/gif \| image/webp	Required with `data`; refused with `url` (the server sends the type).
`filename`	string	Shown in the library. Defaults to the URL's file name, or `image`.
`alt`	string \| null	Alt text suggested when the image is inserted.

Response · 201 fields12 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`path`required	string	Put this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
`url`required	string	The image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
`filename`required	string	—
`content_type`required	string	—
`size`required	integer	Bytes.
`width`required	integer \| null	—
`height`required	integer \| null	—
`alt`required	string \| null	The alt text suggested when the image is inserted.
`created_at`required	string	—
`updated_at`required	string	—

201400401403409422429502503

Retrieve an image

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

GET /library-images/{id}

curl -X GET 'https://www.unitpost.com/api/v1/library-images/img_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Response · 200

{
  "object": "library_image",
  "id": "id_123",
  "path": "string",
  "url": "https://example.com",
  "filename": "string",
  "content_type": "string",
  "size": 1,
  "width": 0,
  "height": 0,
  "alt": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

One library image. Requires the templates:read capability.

Parameters1 field

Field	Type	Description
`id`required	string · path	—

Response · 200 fields12 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`path`required	string	Put this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
`url`required	string	The image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
`filename`required	string	—
`content_type`required	string	—
`size`required	integer	Bytes.
`width`required	integer \| null	—
`height`required	integer \| null	—
`alt`required	string \| null	The alt text suggested when the image is inserted.
`created_at`required	string	—
`updated_at`required	string	—

200401403404422

Update an image

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

PATCH /library-images/{id}

curl -X PATCH 'https://www.unitpost.com/api/v1/library-images/img_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'

Response · 200

{
  "object": "library_image",
  "id": "id_123",
  "path": "string",
  "url": "https://example.com",
  "filename": "string",
  "content_type": "string",
  "size": 1,
  "width": 0,
  "height": 0,
  "alt": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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

Parameters1 field

Field	Type	Description
`id`required	string · path	—

Request body1 field

Field	Type	Description
`alt`required	string \| null	The new alt text; `null` or `""` clears it.

Response · 200 fields12 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`path`required	string	Put this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
`url`required	string	The image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
`filename`required	string	—
`content_type`required	string	—
`size`required	integer	Bytes.
`width`required	integer \| null	—
`height`required	integer \| null	—
`alt`required	string \| null	The alt text suggested when the image is inserted.
`created_at`required	string	—
`updated_at`required	string	—

200400401403404422

Delete an image

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

DELETE /library-images/{id}

curl -X DELETE 'https://www.unitpost.com/api/v1/library-images/img_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

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.

Parameters2 fields

Field	Type	Description
`id`required	string · path	—
`force`	string · query	`true` deletes an image that's in use.

204401403404409422

Library images

List images

Upload an image

Retrieve an image

Update an image

Delete an image

Search docs and guides