# Add Image

`POST https://api.inboxjot.com/v1/images`

Adds an uploaded image to the media library. Send the `key` from Create Image Upload URL. To use an image that is already online, put its URL straight into the email's content. Needs a Full key. A key limited to one domain answers 403. Send an optional `Idempotency-Key` header to retry safely. See Idempotency.

Inboxjot stores the image as you send it, so resize it first. Keep it 1,200 pixels wide or less and under 1 MB.

## Body Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | Yes | The `key` from Create Image Upload URL. |
| `file_name` | string \| null | No | The file name, up to 255 characters. Defaults to `image`. |

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | No | The image id. |
| `file_name` | string | No | The file name. |
| `url` | string \| null | No | The hosted URL to use in an `img` tag. |
| `content_type` | string | No | `image/png`, `image/jpeg` or `image/gif`. |
| `size_bytes` | integer | No | The size in bytes. |
| `width` | integer | No | The width in pixels. |
| `height` | integer | No | The height in pixels. |
| `creator_name` | string \| null | No | The team member who uploaded it. |
| `created_at` | string | No | When it was added. |

## Request

cURL:

```bash
curl -X POST https://api.inboxjot.com/v1/images \
  -H "Authorization: Bearer $INBOXJOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "image-uploads/ws_06d2mfk8r1/0b9e6e5a-3c1f-4c55-9d3a-6f0d2a7c1e44",
    "file_name": "hero.png"
  }'
```

## Responses

| Status | Description |
| --- | --- |
| 201 | Added the image. |
| 400 | A field is missing or invalid, or the Idempotency-Key header is not valid. |
| 401 | The API key is missing, revoked or expired. |
| 403 | The key is a Sending key or is limited to one domain, or the request comes from outside its IP allowlist. |
| 409 | A request with the same Idempotency-Key is still running. Retry after one second. |
| 413 | The body is larger than 2 MB. |
| 415 | The Content-Type header is not application/json. |
| 422 | The Idempotency-Key was already used with a different request. |
| 429 | Too many requests for this key. Wait for the seconds in the Retry-After header. |
| 500 | Something failed on our side. Retry later. |

201:

```json
{
  "id": "img_06d2mfk8r3wn5gt7kc2pb",
  "file_name": "hero.png",
  "url": "https://images.inboxjot-cdn.com/media/ws_06d2mfk8r1/i/3f9a2c1b7e4d6a05.png",
  "content_type": "image/png",
  "size_bytes": 412000,
  "width": 1200,
  "height": 630,
  "creator_name": null,
  "created_at": "2026-10-30T09:00:00.000Z"
}
```

400:

```json
{
  "name": "validation_error",
  "status": 400,
  "message": "Invalid upload key",
  "errors": [
    {
      "message": "Invalid upload key",
      "location": "key"
    }
  ],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

401:

```json
{
  "name": "unauthorized",
  "status": 401,
  "message": "Unauthorized",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

403:

```json
{
  "name": "forbidden",
  "status": 403,
  "message": "This key cannot be used from 203.0.113.7",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

409:

```json
{
  "name": "concurrent_idempotent_requests",
  "status": 409,
  "message": "A request with this idempotency key is still in progress. Try again later.",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

413:

```json
{
  "name": "payload_too_large",
  "status": 413,
  "message": "The request body is too large",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

415:

```json
{
  "name": "unsupported_media_type",
  "status": 415,
  "message": "The Content-Type must be application/json",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

422:

```json
{
  "name": "invalid_idempotent_request",
  "status": 422,
  "message": "This idempotency key was already used with a different request",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

429:

```json
{
  "name": "rate_limit_exceeded",
  "status": 429,
  "message": "Too many attempts. Try again later.",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

500:

```json
{
  "name": "unknown_error",
  "status": 500,
  "message": "Something went wrong. Please try again later.",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```