# Images

Images hosted for use in your emails.

## List images

`GET /projects/{project_id}/images`

Newest first.

### Parameters

| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `project_id` | path | string | Required |
| `cursor` | query | string \| null | Optional |
| `limit` | query | integer | Optional, default 50 |

```sh Request
curl "https://sendocado.com/api/v1/projects/$PROJECT_ID/images" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY"
```

### Response

```json 200
{
  "images": [
    {
      "id": "6mp6afqfjzczbttof7jyu5jsjc616i76",
      "project_id": "ujzde8gxd6ncf10epf91dhodzdoc9is0",
      "url": "https://cdn.sendocado.com/images/2f6b0c1e-8d4a-4f3b-9e7a-5c1d2b3a4f60.png",
      "file_name": "dashboard.png",
      "content_type": "image/png",
      "size_bytes": 184320,
      "created_at": 1790086400000
    }
  ],
  "next_cursor": null
}
```

### Errors

| Status | Type | Example message |
| --- | --- | --- |
| 400 | `invalid_data` | limit: Too big: expected number to be <=200 |
| 401 | `unauthorized` | Send a valid API key as "Authorization: Bearer sc_…", or sign in. |
| 404 | `project_not_found` | Project not found. |
| 429 | `rate_limited` | Too many requests. Try again in 12 seconds. |

## Upload an image

`POST /projects/{project_id}/images`

A PNG, JPEG, GIF or WebP image of up to 5 MB, as a multipart file or as a JSON url Sendocado downloads. The type is read from the file itself. Use the returned url in your emails.

### Parameters

| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `project_id` | path | string | Required |

### Body

Send JSON, or multipart/form-data with the file in `file`.

| Field | Type | Notes |
| --- | --- | --- |
| `file` | file \| null | Optional |
| `url` | string \| null | Optional |
| `file_name` | string \| null | Optional |

```sh Request
curl -X POST "https://sendocado.com/api/v1/projects/$PROJECT_ID/images" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file": null,
  "url": "https://acme.example/press/dashboard.png",
  "file_name": null
}'
```

### Response

```json 201
{
  "id": "6mp6afqfjzczbttof7jyu5jsjc616i76",
  "project_id": "ujzde8gxd6ncf10epf91dhodzdoc9is0",
  "url": "https://cdn.sendocado.com/images/2f6b0c1e-8d4a-4f3b-9e7a-5c1d2b3a4f60.png",
  "file_name": "dashboard.png",
  "content_type": "image/png",
  "size_bytes": 184320,
  "created_at": 1790086400000
}
```

### Errors

| Status | Type | Example message |
| --- | --- | --- |
| 400 | `invalid_data` | Send a JSON request body. |
| 401 | `unauthorized` | Send a valid API key as "Authorization: Bearer sc_…", or sign in. |
| 404 | `project_not_found` | Project not found. |
| 429 | `rate_limited` | Too many requests. Try again in 12 seconds. |

## Delete an image

`DELETE /images/{image_id}`

Emails already sent keep the image’s url, and it stops loading in them.

### Parameters

| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `image_id` | path | string | Required |

```sh Request
curl -X DELETE "https://sendocado.com/api/v1/images/$IMAGE_ID" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY"
```

### Response

`204` with no body.

### Errors

| Status | Type | Example message |
| --- | --- | --- |
| 401 | `unauthorized` | Send a valid API key as "Authorization: Bearer sc_…", or sign in. |
| 404 | `image_not_found` | Image not found. |
| 429 | `rate_limited` | Too many requests. Try again in 12 seconds. |