Metadata-Version: 2.4
Name: samotpravil
Version: 1.0.0rc1
Summary: Python client for Samotpravil SMTP API
Project-URL: Homepage, https://samotpravil.ru/
Project-URL: Documentation, https://documentation.samotpravil.ru/view/26779685/2s93RZM9in
Author-email: Samotpravil <support@samotpravil.ru>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10.0
Requires-Dist: requests>=2.32.3
Provides-Extra: async
Requires-Dist: httpx>=0.27; extra == 'async'
Description-Content-Type: text/markdown

# Sam Optravil

Python библиотека для сервиса Sam Optravil.

[Официальный сайт](https://samotpravil.ru/)

[Подробная документация REST API](https://documentation.samotpravil.ru/view/26779685/2s93RZM9in)

Библиотека является оберткой для API методов

## Установка

```bash
pip install samotpravil
```

Для асинхронного клиента установите дополнительную зависимость:

```bash
pip install "samotpravil[async]"
```

## Начало работы

```python
from samotpravil import SamotpravilClient

# Инициализация
service = SamotpravilClient('*****************')
```
Запросите доступы, [заполнив форму](https://samotpravil.ru/get-access).

## Асинхронный клиент

```python
import asyncio

from samotpravil import AsyncSamotpravilClient


async def main():
    async with AsyncSamotpravilClient('*****************') as service:
        result = await service.send_email(
            email_to='email@example.com',
            subject='Hello from async client',
            message_text='Hello world',
            email_from='info@samotpravil.ru',
        )
        print(result)


if __name__ == '__main__':
    asyncio.run(main())
```

В Jupyter/IPython можно вызывать методы напрямую через `await`, без `asyncio.run(...)`.

## Методы
Отправить письмо. [Описание в API документации](https://documentation.samotpravil.ru/#15015693-d4bd-4b55-a319-e8402d96d062)
```python
service.send_email(email_to='email@example.com',
                   subject='Hello from library',
                   message_text='Hello world',
                   email_from='info@samotpravil.ru')
```

### Обязательные поля
- `email_to` - имейл получателя (str)
- `subject` - тема письма (str)
- `message_text` - текст письма с поддержкой HTML (str)
- `email_from` - имейл отправителя (str)
### Необязательные поля
- `params` - массив собственных переменных (dict)
- `x_track_id` - ваш уникальный ID отправки (str)
- `track_open` - отслеживать открытия (bool)
- `track_click` - отслеживать клики (bool)
- `track_domain` - домен трекинга (str)
- `check_stop_list` - проверять по глобальному стоп-листу (bool)
- `check_local_stop_list` - проверять по клиентскому стоп-листу (bool)
- `domain_for_dkim` - домен для DKIM
- `headers` - свои заголовки (dict)




---
Получить статус доставки. [Описание в API документации](https://documentation.samotpravil.ru/#0cee65d5-4fe3-4efb-916a-23759269bfc7)
```python
service.get_status(message_id='1qBv3w-0007Ls-CS11')
```
### Обязательные поля
- `message_id` - уникальный ID отправки системы (str)

или
- `x_track_id` - ваш ID отправки системы (str)





---
Получить статистику. [Описание в API документации](https://documentation.samotpravil.ru/#8a425ab8-8cbc-4c35-9242-16deb884d634)
```python
service.get_statistics(date_from='2024-10-01',
                       date_to='2024-10-31')
```
### Обязательные поля
- `date_from` - дата в формате YYYY-MM-DD (str)
- `date_to` - дата в формате YYYY-MM-DD (str)
### Необязательные поля
- `limit` - лимит объектов в ответе, дефолт - 100 (int)
- `cursor_next` - пагинация (int)




---
Получить отчет о недоставках за период. [Описание в API документации](https://documentation.samotpravil.ru/#f7a7690a-ad7c-4cc0-ac03-301200259199)
```python
service.get_non_delivery_by_date(date_from='2024-10-01',
                                 date_to='2024-10-31')
```
### Обязательные поля
- `date_from` - дата в формате YYYY-MM-DD (str)
- `date_to` - дата в формате YYYY-MM-DD (str)
### Необязательные поля
- `limit` - лимит объектов в ответе, дефолт - 100 (int)
- `cursor_next` - пагинация (int)



---
Получить отчет о недоставках по номеру выпуска. [Описание в API документации](https://documentation.samotpravil.ru/#01de9691-fe9d-47aa-b00b-35c97091ea5a)
```python
service.get_non_delivery_by_issue(issuen=12345)
```
### Обязательные поля
- `issuen` - ID выпуска (int)



---
Получить отчет о жалобах за период. [Описание в API документации](https://documentation.samotpravil.ru/#49ddff28-6b93-48fa-a7fc-0fbd63a73791)
```python
service.get_fbl_report_by_date(date_from='2024-10-01',
                               date_to='2024-10-31')
```
### Обязательные поля
- `date_from` - дата в формате YYYY-MM-DD (str)
- `date_to` - дата в формате YYYY-MM-DD (str)
### Необязательные поля
- `limit` - лимит объектов в ответе, дефолт - 100 (int)
- `cursor_next` - пагинация (int)




---
Получить отчет о жалобах по номеру выпуска. [Описание в API документации](https://documentation.samotpravil.ru/#9b28ba17-7fd4-4e80-b647-c9baf9d2d979)
```python
service.get_fbl_report_by_issue(issuen=12345)
```
### Обязательные поля
- `issuen` - ID выпуска (int)



---
Искать имейл в стоп-листе. [Описание в API документации](https://documentation.samotpravil.ru/#56ba4dd4-2f5a-4764-9b5c-434d76bcfc2d)
```python
service.stop_list_search(email='example@mail.com')
```
### Обязательные поля
- `email` - имейл, который нужно найти (str)



---
Добавить имейл в стоп-лист. [Описание в API документации](https://documentation.samotpravil.ru/#cf6dbfae-04e1-4fcf-847e-2c977a4db3b5)
```python
service.stop_list_add(email='example@mail.com',
                      domain='samotpravil.ru')
```
### Обязательные поля
- `email` - имейл, который нужно добавить (str)
- `domain` - домен, для которого нужно добавить в стоп-лист (str)



---
Удалить имейл из стоп-листа. [Описание в API документации](https://documentation.samotpravil.ru/#e3357191-6c9f-4bb7-9651-e99cb63dc8bb)
```python
service.stop_list_remove(email='example@mail.com',
                         domain='samotpravil.ru')
```
### Обязательные поля
- `email` - имейл, который нужно удалить (str)
- `domain` - домен, для которого нужно удалить имейл из стоп-листа (str)





---
Получить список разрешенных доменов. [Описание в API документации](https://documentation.samotpravil.ru/#def0eb00-3660-4713-8bfe-accd2efc89b6)
```python
service.get_domains()
```


---
Добавить домен в разрешенные. [Описание в API документации](https://documentation.samotpravil.ru/#372d5d44-eb09-4eda-8895-3dedc2fde511)
```python
service.domain_add(domain='samotpravil.ru')
```
### Обязательные поля
- `domain` - домен, который нужно добавить (str)



---
Удалить домен из разрешенных. [Описание в API документации](https://documentation.samotpravil.ru/#9a51577c-4e58-4ec7-aef1-53d5530d66aa)
```python
service.domain_remove(domain='samotpravil.ru')
```
### Обязательные поля
- `domain` - домен, который нужно удалить (str)


---
Проверить верификацию домена. [Описание в API документации](https://documentation.samotpravil.ru/#ddb3a718-c74e-41ce-ae8f-77e2ff585b1a)
```python
service.domain_check_verification(domain='samotpravil.ru')
```
### Обязательные поля
- `domain` - домен, который нужно проверить (str)



---
Массовая отправка писем. [Описание в API документации](https://documentation.samotpravil.ru/view/26779685/2s93RZM9in#91fa5d31-0228-48ed-81b1-f578a21d325b)
```python
users = [
    {'emailto': 'user1@example.com'},
    {'emailto': 'user2@example.com', 'field1': 'Custom Value'}
]

service.send_package(email_from='info@samotpravil.ru',
                     name_from='Samotpravil',
                     subject='Newsletter',
                     message_text='<h1>Hello</h1><p>Newsletter content</p>',
                     users=users)
```
### Обязательные поля
- `email_from` - имейл отправителя (str)
- `name_from` - имя отправителя (str)
- `subject` - тема письма (str)
- `message_text` - текст письма с поддержкой HTML (str)
- `users` - список получателей, каждый элемент - словарь с ключом `emailto` и опциональными полями для персонализации (list)
### Необязательные поля
- `message_text_amp` - текст письма в формате AMP (str)
- `check_local_stop_list` - проверять по локальному стоп-листу (bool)
- `check_global_stop_list` - проверять по глобальному стоп-листу (bool)
- `track_open` - отслеживать открытия (bool)
- `track_click` - отслеживать клики (bool)
- `track_domain` - домен трекинга (str)
- `headers` - свои заголовки (dict)
- `is_moderate` - флаг для модерации письма (bool)
- `html_prettify` - автоматическое форматирование HTML письма (bool)



---
Массовая отправка через XML-пакет по URL. [Описание в API документации](https://documentation.samotpravil.ru/#9dbf38c0-8438-465a-bac6-66508500f419)
```python
service.send_package_xml(url='https://example.com/xml_package.xml')
```
### Обязательные поля
- `url` - ссылка на XML-файл пакета (str)



---
Остановить пакетную отправку. [Описание в API документации](https://documentation.samotpravil.ru/#520e251f-5a15-4f60-94e0-f5e088100209)
```python
service.stop_package(package_id='66677')
```
### Обязательные поля
- `package_id` - ID пакета, который нужно остановить (str)



---
Получить статус пакета. [Описание в API документации](https://documentation.samotpravil.ru/#075a17c2-e0e7-4b36-9e77-b046667e982f)
```python
service.get_package_status(package_id='123456')
```
### Обязательные поля
- `package_id` - числовой ID пакета (str)



---
Получить всю историю статусов доставки. [Описание в API документации](https://documentation.samotpravil.ru/#cbc5af90-35a5-4067-aee3-48bf873cd7c8)
```python
service.get_ext_status(message_id='1qBv3w-0007Ls-CS11')
```
### Обязательные поля
- `message_id` - уникальный ID отправки системы (str)

или
- `x_track_id` - ваш ID отправки системы (str)



---
Получить отчет об отписках за период. [Описание в API документации](https://documentation.samotpravil.ru/#83d71d3e-165b-44fd-839c-b8309aa8d0ea)
```python
service.get_unsubscribe_by_date(date_from='2024-10-01',
                                date_to='2024-10-31')
```
### Обязательные поля
- `date_from` - дата в формате YYYY-MM-DD (str)
- `date_to` - дата в формате YYYY-MM-DD (str)
### Необязательные поля
- `limit` - лимит объектов в ответе, дефолт - 100 (int)
- `cursor_next` - пагинация (int)
- `order` - порядок сортировки, asc или desc (str)



---
Получить отчет об отписках по номеру выпуска. [Описание в API документации](https://documentation.samotpravil.ru/#c13b5e7f-80c1-4c36-be73-c81779dbae1d)
```python
service.get_unsubscribe_by_issue(issuen=12345)
```
### Обязательные поля
- `issuen` - ID выпуска (int)
### Необязательные поля
- `limit` - лимит объектов в ответе, дефолт - 100 (int)
- `cursor_next` - пагинация (int)
- `order` - порядок сортировки, asc или desc (str)



---
Получить отчет по выпуску(ам) пакетной отправки. [Описание в API документации](https://documentation.samotpravil.ru/#39c6d505-bb61-4190-9c5b-e587467df9ed)
```python
service.get_issue_stat(ids=[66633, 66634])
```
### Обязательные поля
- `ids` - список ID пакетов, которые вернулись в методе отправки (list)



---
Получить стоп-лист отписавшихся имейлов. [Описание в API документации](https://documentation.samotpravil.ru/#8c9baefc-e57b-4b28-9a3c-2e23189a9b9a)
```python
service.stop_list_unsubscribe()
```
### Необязательные поля
- `limit` - лимит объектов в ответе, дефолт - 50 (int)
- `cursor_next` - пагинация (int)



---
Получить стоп-лист пожаловавшихся имейлов (FBL). [Описание в API документации](https://documentation.samotpravil.ru/#0da81108-fec2-4da4-8f38-3fadb30442a4)
```python
service.stop_list_fbl()
```
### Необязательные поля
- `limit` - лимит объектов в ответе, дефолт - 50 (int)
- `cursor_next` - пагинация (int)



---
Получить стоп-лист имейлов с недоставками. [Описание в API документации](https://documentation.samotpravil.ru/#d0852f14-813e-42a4-b67c-6850ab7baf68)
```python
service.stop_list_failed()
```
### Необязательные поля
- `limit` - лимит объектов в ответе, дефолт - 50 (int)
- `cursor_next` - пагинация (int)



---
Создать задачу на экспорт стоп-листа. Возвращает ссылку для скачивания .csv файла в архиве. [Описание в API документации](https://documentation.samotpravil.ru/#2bfe3214-cd3e-46b8-b2da-6ca8305ceff3)
```python
service.stop_list_export_create()
```



---
Получить список задач на экспорт стоп-листа. [Описание в API документации](https://documentation.samotpravil.ru/#b0de4829-2d5f-4145-ab05-c406bfd4ae28)
```python
service.stop_list_export_tasks()
```
### Необязательные поля
- `status` - фильтр по статусу: processing, ready, not_found, failed (str)



---
Скачать архив стоп-листа по токену задачи. Возвращает объект `requests.Response`: код 204 - файл ещё не готов, код 200 - тело содержит .gz архив с csv файлом. [Описание в API документации](https://documentation.samotpravil.ru/#13dfb13f-661b-4f5f-847f-847a6f394745)
```python
response = service.stop_list_export_download(token='some_export_name.csv.gz')
```
### Обязательные поля
- `token` - токен задачи, полученный при создании экспорта (str)



---
Удалить (отменить) задачу на экспорт стоп-листа. [Описание в API документации](https://documentation.samotpravil.ru/#baae5c2c-76aa-48b3-a7f1-c9afb15b8494)
```python
service.stop_list_export_delete(token='some_export_name.csv.gz')
```
### Обязательные поля
- `token` - токен задачи (str)



## Методы для клиентов WhiteLabel
Данная группа методов доступна только клиентам WhiteLabel.

---
Получить информацию о рассылке. [Описание в API документации](https://documentation.samotpravil.ru/#1e5f2843-4bff-47a2-add7-45bcef51bba8)
```python
service.get_blist(blist_id=123)
```
### Обязательные поля
- `blist_id` - ID рассылки (str)



---
Создать рассылку. [Описание в API документации](https://documentation.samotpravil.ru/#530de922-c273-41e2-8872-fd211c173847)
```python
service.create_blist(name='some_name',
                     check_stop_list=True,
                     webhook_active=True,
                     webhook_url='https://webhook.samotpravil.ru/endpoint')
```
### Обязательные поля
- `name` - название рассылки (str)
### Необязательные поля
- `check_stop_list` - проверка по глобальному стоп-листу (bool)
- `webhook_active` - включить Webhook (bool)
- `webhook_url` - URL вебхука (str)
- `web_hook_send_accepted_delivered` - отправлять статусы accepted и delivered (bool)
- `webhook_send_xml_failed_global` - отправлять имейлы из глобального стоп-листа по XML отправкам (bool)



---
Обновить рассылку. [Описание в API документации](https://documentation.samotpravil.ru/#6b19431b-f85e-446f-b62c-1c42f6dc6dd2)
```python
service.update_blist(blist_id=1234,
                     active=False,
                     name='some name')
```
### Обязательные поля
- `blist_id` - ID рассылки (str)
### Необязательные поля
- `active` - активность рассылки (bool)
- `name` - название рассылки (str)
- `check_stop_list` - проверка по глобальному стоп-листу (bool)
- `webhook_active` - включить Webhook (bool)
- `webhook_url` - URL вебхука (str)
- `web_hook_send_accepted_delivered` - отправлять статусы accepted и delivered (bool)
- `webhook_send_xml_failed_global` - отправлять имейлы из глобального стоп-листа по XML отправкам (bool)



---
Получить информацию об IP-адресах, с которых производится отправка. [Описание в API документации](https://documentation.samotpravil.ru/#2b7d3116-4c04-4119-910e-a6c3b31f6467)
```python
service.get_ip_info()
```



---
Получить информацию об API-ключе. [Описание в API документации](https://documentation.samotpravil.ru/#2e5fa91d-bafb-461f-bf36-8f13b48ee411)
```python
service.get_authkey()
```



---
Создать API-ключ. [Описание в API документации](https://documentation.samotpravil.ru/#508c3cc5-5f20-49be-bb15-c4c6afe945a4)
```python
service.create_authkey(blist_id=123,
                       check_ips=True,
                       allowed_ips=['192.168.0.1'])
```
### Обязательные поля
- `blist_id` - ID рассылки (int)
### Необязательные поля
- `check_ips` - включить доступ к ключу по IP-адресу (bool)
- `allowed_ips` - массив разрешённых IP-адресов (list)
