API blmailo: почта в вашем проекте

Быстрый старт

1. Зарегистрируйте адрес на blmailo.com/register или войдите в свой аккаунт.
2. Откройте «Настройки» → «Личная информация» → «Ключ» и нажмите «Создать ключ API». Ключ вида blm_live_… показывается один раз — сохраните его.
3. Передавайте ключ в заголовке Authorization каждого запроса.

curl -H "Authorization: Bearer blm_live_ВАШ_КЛЮЧ" https://blmailo.com/api/v1/status

Ответ:

{"ok": true, "domain": "blmailo.com", "account": "name@blmailo.com", "remaining": 0, "owned_addresses": 0}

Основное

• Базовый адрес: https://blmailo.com/api/v1. Только HTTPS.
• Запросы и ответы — JSON в UTF-8. Для запросов с телом указывайте Content-Type: application/json.
• Почти во всех методах нужен параметр email — адрес, с которым вы работаете: ваш собственный или созданный вами через API.
• Ключ действует от имени вашего аккаунта и видит только вашу почту и ваши адреса. Чужие ящики недоступны.
• Можно создать до 5 ключей на аккаунт. Ключ отзывается в тех же настройках и перестаёт работать сразу.

Лимиты

• Обычный аккаунт: 300 запросов в час и 3000 в сутки.
• Аккаунт с активированным ключом адресов: 1200 запросов в час и 10 000 в сутки.
• Ответы на письма: до 60 в час и 300 в сутки внутри blmailo, до 20 в час и 100 в сутки на внешние адреса.
• Создание адресов: до 60 в час и 500 в сутки, в пределах остатка на ключе.
• При превышении лимита приходит ответ 429. Повторите запрос позже.

Письма

curl -H "Authorization: Bearer blm_live_ВАШ_КЛЮЧ" \
  "https://blmailo.com/api/v1/messages?email=name@blmailo.com&folder=inbox&limit=20"

curl -X PATCH -H "Authorization: Bearer blm_live_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"action": "read", "value": true}' "https://blmailo.com/api/v1/messages/123?email=name@blmailo.com"

curl -X POST -H "Authorization: Bearer blm_live_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"body": "Спасибо, получил."}' "https://blmailo.com/api/v1/messages/123/reply?email=name@blmailo.com"

Адреса

Создавать новые адреса через API может аккаунт с активированным ключом адресов: каждый адрес списывается с остатка ключа. Пакет адресов покупается на странице blmailo.com/billing.

curl -X POST -H "Authorization: Bearer blm_live_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"email": "shop-01@blmailo.com", "display_name": "Shop", "password": "длинный-пароль"}' https://blmailo.com/api/v1/accounts

Коды ответов

• 200, 201 — запрос выполнен.
• 400 — ошибка в параметрах.
• 401 — ключ не передан, неверен или отозван.
• 402 — на ключе не осталось адресов.
• 404 — адрес или письмо не найдены либо не принадлежат вам.
• 409 — такой адрес уже занят.
• 429 — превышен лимит запросов.
• 500, 502 — ошибка на стороне сервера, повторите позже.

При ошибке в ответе есть поле error с описанием.

Пример на Python

import requests

API = "https://blmailo.com/api/v1"
HEADERS = {"Authorization": "Bearer blm_live_ВАШ_КЛЮЧ"}
EMAIL = "name@blmailo.com"

last_id = 0
response = requests.get(f"{API}/messages", headers=HEADERS,
                        params={"email": EMAIL, "after_id": last_id}, timeout=30)
response.raise_for_status()
data = response.json()
for message in data["messages"]:
    print(message["id"], message["sender"], message["subject"])
last_id = data["next_after_id"]

Правила использования

• Храните ключ в секрете: не публикуйте его в коде, репозиториях и на страницах сайта. Вызывайте API со своего сервера, а не из браузера посетителя.
• Если ключ мог попасть к посторонним, отзовите его и создайте новый. При восстановлении пароля все ключи аккаунта отзываются автоматически.
• Запрещены рассылка спама, массовые автоматические регистрации на чужих сервисах и любые действия, нарушающие условия использования. За это ключ и аккаунт блокируются.
• Не опрашивайте почту чаще, чем нужно: раз в 10–30 секунд достаточно почти для любой задачи.