Images

All endpoints on this page require Authorization: Bearer {session_token} from the session endpoint and the embedded headers.

Files land in the plugin's own bucket if one is attached, otherwise on MailEditor storage. Files written before a bucket was attached stay where they are. Images are scoped to the external_user_id on the session, exactly as templates are.

A bucket needs a public URL before it can hold images

An image ends up as an <img src> in an email that may be opened months later, so it must be reachable by a stable URL. If custom storage has no public_url, uploads are refused with 409 storage_not_public. Set Public URL on the Custom Storage tab to a CDN or custom domain that serves the bucket.

Stock photos from Unsplash, Pexels and Pixabay are a separate surface, on Stock images. A Pixabay picture is imported into this library and then behaves like an upload.

Limits. 5 MB per image; PNG, JPEG, GIF and WebP. SVG is not accepted. Batch uploads take at most 10 files per request. Uploads are limited to 20 per minute and 200 per hour per session.

The image object

{
  "uuid": "9f1c…",
  "name": "9f1c…",
  "admin_uploaded": false,
  "used_in_banner": false,
  "path": "https://cdn.customer.com/9/9f1c….png",
  "external_user_id": "user-42"
}

Field	Notes
`uuid`	The identifier for delete and for setting properties. There is no numeric id
`name`	A generated uuid. The original filename is not stored
`admin_uploaded`	Always `false` for a plugin upload
`used_in_banner`	`false` unless you set it with tag an image
`path`	The URL to put in the template
`external_user_id`	The id the session declared. `null` for an anonymous session

List images

GET /public/plugin/v1/images

Query	Default	Notes
`search`		Matches the stored name
`per_page`	`21`	Capped at 100
`page`	`1`

Newest first.

{
  "message": "Images fetched successfully",
  "result": {
    "images": {
      "data": [ { "uuid": "9f1c…", "path": "https://cdn.customer.com/…", "…": "…" } ],
      "links": { "first": "…", "last": "…", "prev": null, "next": null },
      "meta": { "current_page": 1, "per_page": 21, "total": 1 }
    }
  }
}

Upload an image

POST /public/plugin/v1/images
Content-Type: multipart/form-data

Field	Required	Notes
`image`	yes	PNG, JPEG, GIF or WebP, max 5 MB

201

{
  "message": "Image uploaded successfully",
  "result": {
    "uploaded_image": { "uuid": "9f1c…", "path": "https://cdn.customer.com/…", "…": "…" }
  }
}

Status	`result.error`	Meaning
409	`storage_not_public`	Custom storage has no `public_url`. Nothing was written
422		Wrong type, or larger than 5 MB
429		Upload rate limit

Upload several images

POST /public/plugin/v1/images/multiple
Content-Type: multipart/form-data

Field	Required	Notes
`images[]`	yes	1 to 10 files, each subject to the same rules as a single upload

201 with result.uploaded_images as an array of image objects. If any file is rejected, none are stored.

Delete an image

DELETE /public/plugin/v1/images/{uuid}

Removes the record and the file. 404 image_not_found if the uuid is not this end user's or does not exist.

Delete several images

DELETE /public/plugin/v1/images/multiple

{ "uuids": ["9f1c…", "3b7e…"] }

1 to 50 uuids. Returns how many were removed. A uuid that is not this end user's is skipped.

{ "message": "Images deleted successfully", "result": { "deleted": 1 } }

Tag an image

POST /public/plugin/v1/images/{uuid}/add-custom-property

Field	Type	Required	Notes
`key`	string	yes	Must be `used_in_banner`
`value`	boolean	yes	`true` or `false`; `1`/`0` and `"1"`/`"0"` for form posts

{ "key": "used_in_banner", "value": true }

200 returns result.image, the full image object with used_in_banner updated.

Status	`error`	Meaning
404	`image_not_found`	Not this end user's, or no such uuid
422	`unsupported_image_property`	A key other than `used_in_banner`. `result.allowed` names what is permitted
422		`key` missing, or `value` not a boolean