Stock images

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

Stock search runs on your own provider keys, attached on the Stock Images tab. MailEditor holds no key of its own for a plugin, so a plugin with no key has no stock library. There is no plan feature to buy and no quota to spend; the provider sets the limits that apply to your key.

Which providers are available comes from curation.stock on bootstrap. There is no separate providers endpoint. The editor hides the Stock Images tab when providers is empty.

"stock": { "is_available": true, "providers": [{ "value": "unsplash", "label": "Unsplash" }] }

Every request names one provider in a provider field. A provider your plugin has no key for fails validation with 422, the same as a misspelled one.

Limits. 30 requests per minute and 300 per hour per session, plus 2000 per hour across the whole plugin. Import counts against the upload limit instead: 20 per minute and 200 per hour per session.

The stock image object

{
  "id": "Qwh5TL0J_7k",
  "url": "https://images.unsplash.com/photo-16…?w=600&h=400&fit=crop&crop=entropy&fm=jpg&q=80",
  "thumb_url": "https://images.unsplash.com/photo-16…?w=400",
  "alt": "a laptop on a wooden desk",
  "download_location": "https://api.unsplash.com/photos/Qwh5TL0J_7k/download",
  "credit": {
    "name": "Jane Doe",
    "link": "https://unsplash.com/@janedoe?utm_source=my-app&utm_medium=referral",
    "provider": "Unsplash",
    "provider_link": "https://unsplash.com?utm_source=my-app&utm_medium=referral"
  }
}

Search stock images

GET /public/plugin/v1/stock/images?provider=unsplash&search=desk&page=1&width=600&height=400
Authorization: Bearer mep_…

width and height build a cropped, compressed url through the provider's own image CDN, so a 600x400 slot downloads a 600x400 file. Give both or you get the provider's default size back. Pixabay ignores them, because its CDN does not resize.

Page size is fixed by MailEditor and is not a parameter. Read has_more instead of counting results.

200

{
  "message": "Stock images retrieved successfully",
  "result": {
    "images": [ { "id": "Qwh5TL0J_7k", "url": "https://…", "…": "…" } ],
    "has_more": true
  }
}

Track a download

Unsplash's API terms require a call to the photo's download endpoint each time a user picks the image. Pexels and Pixabay have no equivalent, so they return an empty download_location and there is nothing to send.

POST /public/plugin/v1/stock/track-download

{ "provider": "unsplash", "download_location": "https://api.unsplash.com/photos/Qwh5TL0J_7k/download" }

Send it when the user confirms the image, not while browsing. Fire and forget: the response carries no payload, and a provider that fails to answer is logged and swallowed, so a tracking failure never blocks the user.

200

{ "message": "Download tracked", "result": null }

Import an image

Pixabay's terms forbid hotlinking its CDN from a sent email, so a Pixabay picture has to be copied onto your side before it can go in a template. Import downloads it and stores it as a normal image owned by the session's end user.

POST /public/plugin/v1/stock/import

{ "provider": "pixabay", "url": "https://pixabay.com/get/g8f2….jpg" }

201

{
  "message": "Stock image imported successfully",
  "result": {
    "imported_image": { "uuid": "9f1c…", "path": "https://cdn.customer.com/9/9f1c….jpg", "…": "…" }
  }
}

Put imported_image.path in the template. The file lands in your bucket if one is attached, otherwise on MailEditor storage, where it counts against the plan's image_storage quota like any upload. It also shows up in the user's image library and can be deleted from there.