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.requiredisfalseonGET /v1/usage. A workspace with no card on file may well be exempt, so do not decide frompresentalone. Try the upload: a refusal names what is missing.
The media object
Every field is always present.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (UUID). |
filename | string | A 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. |
size | integer | Stored size in bytes. |
width | integer | Width in pixels. |
height | integer | Height in pixels. |
url | string | null | Where 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_at | string (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
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
content | string | One of the two | none | The image, base64-encoded, at most 5 MB decoded. A data: URL is accepted. |
source_url | string | One of the two | none | A 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. |
filename | string | No | The name in source_url, or image | A label for the image, up to 255 characters. |
Example
Response
201 Created when the image was stored, 200 OK when the same bytes were already stored. Either way, a media object.
Then use it:
Always set alt, and set width to the size the image should display at: many mail clients ignore CSS sizing on images.
Errors
| Status | Type | When |
|---|---|---|
| 402 | payment_method_required | The 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. |
| 402 | plan_limit_reached | The workspace already holds 500 images or 250 MB. |
| 409 | invalid_state | No sending domain in the workspace has a live tracking hostname to serve the image from. |
| 413 | payload_too_large | The request body is over 8 MB. |
| 422 | invalid_request | Neither 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. |
| 422 | workspace_suspended | Sending 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
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Page size, at most 100. |
cursor | string | none | The next_cursor from the previous page. |
Response
200 OK
Retrieve an image
GET /v1/media/{id} · requires templates:read
Returns one image's details. The bytes themselves are fetched from url.
Path parameters
| Parameter | Description |
|---|---|
id | The image's id. |
Response
200 OK, a media object.
Errors
| Status | Type | When |
|---|---|---|
| 404 | not_found | No 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
| Parameter | Description |
|---|---|
id | The image's id. |
Response
200 OK
Errors
| Status | Type | When |
|---|---|---|
| 404 | not_found | No image with this id in the workspace. |