# Документация Плимы

> Плима: доменная почта, IMAP/POP3, HTTPS API отправки и чтения, вебхуки.

## Разделы

- [Интеграции с Плимой](https://docs.plima.ru/): Отправляйте письма с сайта, читайте почту через API и подключайте привычные почтовые приложения.
- [Первый запрос](https://docs.plima.ru/quickstart.html): Создайте ключ для одного ящика и отправьте первое сервисное письмо через API Плимы.
- [Ключи и права](https://docs.plima.ru/authentication.html): Выдавайте отдельный API-ключ каждому приложению и выбирайте доступ только к нужному ящику.
- [Отправка писем](https://docs.plima.ru/sending.html): Очередь отправки, квитанции, идемпотентность и срок начала передачи письма.
- [Чтение почты](https://docs.plima.ru/reading.html): Получайте папки, письма и вложения через API Плимы с курсорной пагинацией.
- [IMAP и POP3](https://docs.plima.ru/mail-clients.html): Подключите почтовое приложение с отдельным паролем и защищённым соединением.
- [Вебхуки](https://docs.plima.ru/webhooks.html): Получайте подписанные HTTPS-события об изменениях почты и контролируйте доставку.
- [Лимиты и ошибки](https://docs.plima.ru/limits-errors.html): Обрабатывайте ограничения и ошибки без повторной отправки одного письма.

## Условия

- API base: https://plima.ru/v1. Bearer-ключ связан с одним ящиком. Только backend, без браузерного Origin и CORS.
- Существующие ключи имеют только отправку и квитанции. Чтение требует явно выданного messages:read, файлы также attachments:read.
- Бесплатно: 1 домен, 1 ящик, 1 ГБ, 100 исходящих получателей в календарный месяц суммарно из кабинета и API. Сброс в первый день в 00:00 Europe/Moscow.
- GET чтения не отмечает письма прочитанными. Списки 1..100, по умолчанию 50, курсоры 15 минут; cursor_stale 409 требует начать обход заново, истёкший курсор 410.
- SMTP для сторонних приложений не включён в пароли IMAP/POP3.
- Вебхуки передают метаданные без тела писем; HMAC-SHA256, защита времени и устранение дублей по event.id.
- История /v1/events ведётся только при активных вебхуках, хранится 7 дней; истёкшая позиция 410. Это не архив и не журнал каждого промежуточного действия.
- accepted означает приём SMTP Плимы, а не доставку во Входящие.
- Контакт: support@plima.ru.

## Карта API

| Метод | Путь | Права |
| --- | --- | --- |
| POST | /v1/emails | emails:send |
| GET | /v1/emails/{id} | emails:status |
| GET | /v1/folders | messages:read |
| GET | /v1/messages | messages:read |
| GET | /v1/messages/{id} | messages:read |
| GET | /v1/messages/{id}/raw | messages:read и attachments:read |
| GET | /v1/messages/{id}/attachments/{attachmentId} | messages:read и attachments:read |
| GET | /v1/events | messages:read, история активных вебхуков |

## Почтовые приложения

mail.plima.ru, IMAP 993 SSL/TLS, POP3 995 SSL/TLS.
Логин: полный адрес ящика. Пароль: отдельный пароль приложения.
IMAP позволяет изменять и удалять письма. POP3 может удалить копию с сервера:
включите оставление копий, если они нужны кабинету и API.