Documentation

Media

Upload images once and use them in the HTML of templates, campaigns and automations, served from your own tracking domain.

A media file is an image SendRaven hosts for you, so the HTML of a template, a campaign or an automation step can show a logo or a photo without you running an image host. Upload it once, put the url in an <img src>, and reuse it in as many messages as you like.

Images only. An upload must be a PNG, JPEG, GIF or WebP, at most 5 MB. That is decided from the file's bytes, not from its name, so a PDF renamed logo.png is refused. Documents, PDFs, video and SVG are not accepted. To send a file to a recipient, attach it to the message with attachments instead.

Served from your own domain. The url is on your tracking hostname, https://link.{your sending domain}/media/…, the same hostname that carries your tracked links. Mailbox providers judge a message by where its images come from, and an image on a host shared with other senders is a mark against it. This means a workspace needs one sending domain whose tracking record is live before it can upload; GET /v1/domains shows the record to publish. When a message is sent, each hosted image's URL is moved onto the tracking hostname of the domain that is sending, so mail from mail.example.com and from news.example.com each carries images on its own name.

What happens to an upload

Every image is decoded and written out again before it is stored:

  • Metadata is removed, including EXIF, which on a phone photo records where it was taken.
  • An image wider or taller than 2400 pixels is scaled down to fit. A smaller one is never scaled up.
  • PNG, JPEG and GIF keep their format, and an animated GIF stays animated.
  • WebP is converted, because Outlook on Windows does not display it: to PNG when it has transparency, to JPEG when it does not, and to GIF when it is animated.

So content_type, size, width and height describe the stored image and can differ from the file you sent. Uploading the same bytes a second time stores nothing new and answers the image already stored.

Opening an image is not counted as an open. Opens are recorded only by the tracking pixel SendRaven adds to each message.

Limits

  • 5 MB per image, before and after processing.
  • 500 images and 250 MB per workspace. Delete images no message uses to make room.
  • The workspace needs a verified payment method, as it does to send, unless it is exempt from one: payment_method.required is false on GET /v1/usage. A workspace with no card on file may well be exempt, so do not decide from present alone. Try the upload: a refusal names what is missing.

The media object

Every field is always present.

FieldTypeDescription
idstringUnique identifier (UUID).
filenamestringA label: the name you uploaded it under, with any path removed. It is not part of the URL.
content_type"image/png" | "image/jpeg" | "image/gif"The stored type.
sizeintegerStored size in bytes.
widthintegerWidth in pixels.
heightintegerHeight in pixels.
urlstring | nullWhere the image is served. null when the workspace no longer has a live tracking hostname; the image is still stored and the field returns when one is live again.
created_atstring (ISO 8601)When the image was uploaded.

Upload an image

POST /v1/media · requires templates:write

Stores an image. Pass either the bytes as content or a public source_url to fetch them from, never both. The JSON body may be up to 8 MB.

Body

FieldTypeRequiredDefaultDescription
contentstringOne of the twononeThe image, base64-encoded, at most 5 MB decoded. A data: URL is accepted.
source_urlstringOne of the twononeA public http or https URL to fetch the image from, at most 5 MB. It must answer 200 directly: a redirect is not followed, and a private or internal address is refused.
filenamestringNoThe name in source_url, or imageA label for the image, up to 255 characters.

Example

curl https://api.sendraven.ai/v1/media \
  -X POST \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"filename\": \"logo.png\", \"content\": \"$(base64 < logo.png | tr -d '\n')\" }"

Response

201 Created when the image was stored, 200 OK when the same bytes were already stored. Either way, a media object.

{
  "id": "3f1c9a7e-2b4d-4e6f-8a0c-1d3e5f7a9b2c",
  "filename": "logo.png",
  "content_type": "image/png",
  "size": 18234,
  "width": 600,
  "height": 160,
  "url": "https://link.news.example.com/media/3f1c9a7e-2b4d-4e6f-8a0c-1d3e5f7a9b2c/Zk3vN1q8Rj2LwXy0aBcDeFgHiJk.png",
  "created_at": "2026-11-11T09:00:00.000Z"
}

Then use it:

<img src="https://link.news.example.com/media/3f1c9a7e-2b4d-4e6f-8a0c-1d3e5f7a9b2c/Zk3vN1q8Rj2LwXy0aBcDeFgHiJk.png" alt="Acme" width="300">

Always set alt, and set width to the size the image should display at: many mail clients ignore CSS sizing on images.

Errors

StatusTypeWhen
402payment_method_requiredThe workspace needs a verified payment method and has none. A person has to add one in the dashboard. Only this answer means a card is missing.
402plan_limit_reachedThe workspace already holds 500 images or 250 MB.
409invalid_stateNo sending domain in the workspace has a live tracking hostname to serve the image from.
413payload_too_largeThe request body is over 8 MB.
422invalid_requestNeither or both of content and source_url were given; content is not base64; the file is not a PNG, JPEG, GIF or WebP image, or is over 5 MB; or source_url is not a public URL, answered with a redirect, or did not answer 200.
422workspace_suspendedSending is suspended for the workspace.

List images

GET /v1/media · requires templates:read

Returns the workspace's images newest first, cursor-paged. See Pagination.

Query parameters

ParameterTypeDefaultDescription
limitinteger50Page size, at most 100.
cursorstringnoneThe next_cursor from the previous page.

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "3f1c9a7e-2b4d-4e6f-8a0c-1d3e5f7a9b2c",
      "filename": "logo.png",
      "content_type": "image/png",
      "size": 18234,
      "width": 600,
      "height": 160,
      "url": "https://link.news.example.com/media/3f1c9a7e-2b4d-4e6f-8a0c-1d3e5f7a9b2c/Zk3vN1q8Rj2LwXy0aBcDeFgHiJk.png",
      "created_at": "2026-11-11T09:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve an image

GET /v1/media/{id} · requires templates:read

Returns one image's details. The bytes themselves are fetched from url.

Path parameters

ParameterDescription
idThe image's id.

Response

200 OK, a media object.

Errors

StatusTypeWhen
404not_foundNo image with this id in the workspace.

Delete an image

DELETE /v1/media/{id} · requires templates:write

Deletes the image. Its url stops working within a few minutes, including in email that was already sent and in any template, campaign or automation step that still references it, where it then shows as a broken image. Nothing checks for references first, so delete only what no message uses. A copy held by a mailbox provider's image cache can stay visible for up to a day.

Path parameters

ParameterDescription
idThe image's id.

Response

200 OK

{
  "id": "3f1c9a7e-2b4d-4e6f-8a0c-1d3e5f7a9b2c",
  "deleted": true
}

Errors

StatusTypeWhen
404not_foundNo image with this id in the workspace.

On this page