samotpravil 1.0.0rc1

Python client for Samotpravil SMTP API

Sam Optravil

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

Официальный сайт

Подробная документация REST API

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

Установка

pip install samotpravil

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

pip install "samotpravil[async]"

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

from samotpravil import SamotpravilClient

# Инициализация
service = SamotpravilClient('*****************')

Запросите доступы, заполнив форму.

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

import asyncio

from samotpravil import AsyncSamotpravilClient


async def main():
    async with AsyncSamotpravilClient('*****************') as service:
        result = await service.send_email(
            email_to='[e-mail]',
            subject='Hello from async client',
            message_text='Hello world',
            email_from='[e-mail]',
        )
        print(result)


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

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

Методы

Отправить письмо. Описание в API документации

service.send_email(email_to='[e-mail]',
                   subject='Hello from library',
                   message_text='Hello world',
                   email_from='[e-mail]')

Обязательные поля

• 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 документации

service.get_status(message_id='1qBv3w-0007Ls-CS11')

Обязательные поля

• message_id - уникальный ID отправки системы (str)

или

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

---

Получить статистику. Описание в API документации

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 документации

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 документации

service.get_non_delivery_by_issue(issuen=12345)

Обязательные поля

• issuen - ID выпуска (int)

---

Получить отчет о жалобах за период. Описание в API документации

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 документации

service.get_fbl_report_by_issue(issuen=12345)

Обязательные поля

• issuen - ID выпуска (int)

---

Искать имейл в стоп-листе. Описание в API документации

service.stop_list_search(email='[e-mail]')

Обязательные поля

• email - имейл, который нужно найти (str)

---

Добавить имейл в стоп-лист. Описание в API документации

service.stop_list_add(email='[e-mail]',
                      domain='samotpravil.ru')

Обязательные поля

• email - имейл, который нужно добавить (str)
• domain - домен, для которого нужно добавить в стоп-лист (str)

---

Удалить имейл из стоп-листа. Описание в API документации

service.stop_list_remove(email='[e-mail]',
                         domain='samotpravil.ru')

Обязательные поля

• email - имейл, который нужно удалить (str)
• domain - домен, для которого нужно удалить имейл из стоп-листа (str)

---

Получить список разрешенных доменов. Описание в API документации

service.get_domains()

---

Добавить домен в разрешенные. Описание в API документации

service.domain_add(domain='samotpravil.ru')

Обязательные поля

• domain - домен, который нужно добавить (str)

---

Удалить домен из разрешенных. Описание в API документации

service.domain_remove(domain='samotpravil.ru')

Обязательные поля

• domain - домен, который нужно удалить (str)

---

Проверить верификацию домена. Описание в API документации

service.domain_check_verification(domain='samotpravil.ru')

Обязательные поля

• domain - домен, который нужно проверить (str)

---

Массовая отправка писем. Описание в API документации

users = [
    {'emailto': '[e-mail]'},
    {'emailto': '[e-mail]', 'field1': 'Custom Value'}
]

service.send_package(email_from='[e-mail]',
                     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 документации

service.send_package_xml(url='https://example.com/xml_package.xml')

Обязательные поля

• url - ссылка на XML-файл пакета (str)

---

Остановить пакетную отправку. Описание в API документации

service.stop_package(package_id='66677')

Обязательные поля

• package_id - ID пакета, который нужно остановить (str)

---

Получить статус пакета. Описание в API документации

service.get_package_status(package_id='123456')

Обязательные поля

• package_id - числовой ID пакета (str)

---

Получить всю историю статусов доставки. Описание в API документации

service.get_ext_status(message_id='1qBv3w-0007Ls-CS11')

Обязательные поля

• message_id - уникальный ID отправки системы (str)

или

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

---

Получить отчет об отписках за период. Описание в API документации

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 документации

service.get_unsubscribe_by_issue(issuen=12345)

Обязательные поля

• issuen - ID выпуска (int)

Необязательные поля

• limit - лимит объектов в ответе, дефолт - 100 (int)
• cursor_next - пагинация (int)
• order - порядок сортировки, asc или desc (str)

---

Получить отчет по выпуску(ам) пакетной отправки. Описание в API документации

service.get_issue_stat(ids=[66633, 66634])

Обязательные поля

• ids - список ID пакетов, которые вернулись в методе отправки (list)

---

Получить стоп-лист отписавшихся имейлов. Описание в API документации

service.stop_list_unsubscribe()

Необязательные поля

• limit - лимит объектов в ответе, дефолт - 50 (int)
• cursor_next - пагинация (int)

---

Получить стоп-лист пожаловавшихся имейлов (FBL). Описание в API документации

service.stop_list_fbl()

Необязательные поля

• limit - лимит объектов в ответе, дефолт - 50 (int)
• cursor_next - пагинация (int)

---

Получить стоп-лист имейлов с недоставками. Описание в API документации

service.stop_list_failed()

Необязательные поля

• limit - лимит объектов в ответе, дефолт - 50 (int)
• cursor_next - пагинация (int)

---

Создать задачу на экспорт стоп-листа. Возвращает ссылку для скачивания .csv файла в архиве. Описание в API документации

service.stop_list_export_create()

---

Получить список задач на экспорт стоп-листа. Описание в API документации

service.stop_list_export_tasks()

Необязательные поля

• status - фильтр по статусу: processing, ready, not_found, failed (str)

---

Скачать архив стоп-листа по токену задачи. Возвращает объект requests.Response: код 204 - файл ещё не готов, код 200 - тело содержит .gz архив с csv файлом. Описание в API документации

response = service.stop_list_export_download(token='some_export_name.csv.gz')

Обязательные поля

• token - токен задачи, полученный при создании экспорта (str)

---

Удалить (отменить) задачу на экспорт стоп-листа. Описание в API документации

service.stop_list_export_delete(token='some_export_name.csv.gz')

Обязательные поля

• token - токен задачи (str)

Методы для клиентов WhiteLabel

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

---

Получить информацию о рассылке. Описание в API документации

service.get_blist(blist_id=123)

Обязательные поля

• blist_id - ID рассылки (str)

---

Создать рассылку. Описание в API документации

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 документации

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 документации

service.get_ip_info()

---

Получить информацию об API-ключе. Описание в API документации

service.get_authkey()

---

Создать API-ключ. Описание в API документации

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)