API картинок: загрузить файл для письма, список, удаление

Ресурс images: тот же файловый менеджер, что в кабинете. Положили файл через API, и он сразу виден в кабинете, а адрес из ответа можно ставить в письмо: он открывается без входа.

Форматы: bmp, gif, jpeg, jpg, png, регистр расширения не важен. SVG нельзя. Содержимое файла должно совпасть с расширением.
Размер: до 2 МБ. Запрос больше 8 МБ сервер отбивает ответом 413 ещё до API, без кода ошибки.
Файл кладётся как есть. Менеджер в кабинете при загрузке ужимает картинку до 1600×1200, API размеры не меняет.
Имя файла и каждая папка: только латинские буквы, цифры, _ и -, до 64 знаков. У файла одно расширение. Вложенность папок до 5. Имена __thumbs и CVS заняты менеджером.
Папка создаётся сама при загрузке. Без folder файл ложится в корень менеджера.
Замена и удаление меняют картинку и в уже отправленных письмах, потому что письмо ссылается на этот адрес. Удалили: в отправленном письме пустое место.
Браузеры и почтовые провайдеры могут хранить картинку до 30 дней, поэтому после замены часть читателей ещё увидит старую. Новой картинке надёжнее дать новое имя или новую папку.

GET`/mailer/images.json`

Подпапки и файлы папки

Параметр	Значение
`folder`	Папка, например `horoscope-daily` или `a/b`. Нет: корень. Такой папки нет: ответ 404.
`limit`, `page`	Страницы для файлов, как в других списках. Без них все файлы. Подпапки приходят всегда все.

Поле	Значение
`folder`	Папка запроса, в корне пустая строка.
`folders`	Подпапки: `name`.
`files`	Файлы по имени: `name`, `size` (байт), `modified` (дата и время сервера), `url`.
`total`	Сколько файлов в папке.

В папке ничего нет: ответ 204. Файлы и папки, созданные в кабинете, тоже есть в списке. Если имя не подходит под правила выше, через API такую папку не открыть, а файл не удалить: это можно в кабинете.

curl -G https://v1.estismail.com/mailer/images.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  -d folder=horoscope-daily

<?php
$query = http_build_query([
    'folder' => 'horoscope-daily',
]);
$ch = curl_init('https://v1.estismail.com/mailer/images.json' . '?' . $query);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.get(
    "https://v1.estismail.com/mailer/images.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    params={
        "folder": "horoscope-daily",
    },
)
print(r.status_code, r.text)

const params = new URLSearchParams({
  folder: "horoscope-daily",
});
const res = await fetch("https://v1.estismail.com/mailer/images.json?" + params, {
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
});
console.log(res.status, await res.text());

Ответ 200

{
  "folder": "horoscope-daily",
  "folders": [
    {
      "name": "archive"
    }
  ],
  "files": [
    {
      "name": "day.jpg",
      "size": 48213,
      "modified": "2026-11-04 12:30:05",
      "url": "https://mailer.estismail.com/images/users/12345/images/horoscope-daily/day.jpg"
    }
  ],
  "total": 1
}

POST`/mailer/images.json`

Положить картинку

Запрос в формате multipart/form-data. Имя файла берётся из самого файла.

Параметр	Значение
`file` обязательный	Один файл картинки.
`folder`	Папка, например `horoscope-daily` или `a/b`. Нет: корень. Папки нет: создаётся.
`replace`	`1`: заменить файл с таким именем. Без него занятое имя даёт ошибку 23008, файл не меняется. Замена происходит разом, половины файла по адресу не бывает.

Поле	Значение
`name`, `folder`	Имя файла и папка.
`url`	Полный адрес, готовый для письма.
`size`	Размер в байтах.
`width`, `height`	Ширина и высота в пикселях.

curl https://v1.estismail.com/mailer/images.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  -F file=@day.jpg \
  -F folder=horoscope-daily

<?php
$ch = curl_init('https://v1.estismail.com/mailer/images.json');
curl_setopt_array($ch, [
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('day.jpg'),
        'folder' => 'horoscope-daily',
    ],
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

with open("day.jpg", "rb") as f:
    r = requests.post(
        "https://v1.estismail.com/mailer/images.json",
        headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
        files={"file": f},
        data={"folder": "horoscope-daily"},
    )
print(r.status_code, r.text)

import { readFileSync } from "node:fs";

const form = new FormData();
form.append("file", new Blob([readFileSync("day.jpg")]), "day.jpg");
form.append("folder", "horoscope-daily");
const res = await fetch("https://v1.estismail.com/mailer/images.json", {
  method: "POST",
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
  body: form,
});
console.log(res.status, await res.text());

Ответ 201 (при замене 200)

{
  "name": "day.jpg",
  "folder": "horoscope-daily",
  "url": "https://mailer.estismail.com/images/users/12345/images/horoscope-daily/day.jpg",
  "size": 48213,
  "width": 600,
  "height": 400
}

DELETE`/mailer/images.json`

Удалить файл

path обязателен: путь файла внутри менеджера, например horoscope-daily/day.jpg. Можно передать в теле запроса или в адресе. Файла нет: ответ 404. Папки не удаляются, даже пустые: папку можно убрать в кабинете. Картинка пропадает и в уже отправленных письмах.

curl -X DELETE https://v1.estismail.com/mailer/images.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  -d path=horoscope-daily/day.jpg

<?php
$ch = curl_init('https://v1.estismail.com/mailer/images.json');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_POSTFIELDS => http_build_query([
        'path' => 'horoscope-daily/day.jpg',
    ]),
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.delete(
    "https://v1.estismail.com/mailer/images.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    data={
        "path": "horoscope-daily/day.jpg",
    },
)
print(r.status_code, r.text)

const res = await fetch("https://v1.estismail.com/mailer/images.json", {
  method: "DELETE",
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
  body: new URLSearchParams({
    path: "horoscope-daily/day.jpg",
  }),
});
console.log(res.status, await res.text());

Ответ 204, без тела

Вопросы по API: support@estismail.com

Картинки

GET/mailer/images.json

POST/mailer/images.json

DELETE/mailer/images.json

GET`/mailer/images.json`

POST`/mailer/images.json`

DELETE`/mailer/images.json`