connectMailbox

Подключает ящик к каналу «Почта» — то же, что «Вход в ящик» в кабинете. Ящики Gmail, Outlook, Яндекса и Mail подключаются входом через сервис: метод вернёт ссылку на страницу входа. Остальная почта — по логину и паролю: метод проверит вход и отправку сразу.

Как выбирается способ входа

Если вход через сервис для этой почты недоступен, нужен пароль. Gmail в этом случае пускает только по паролю приложения; iCloud и часть ящиков Яндекса и Mail тоже пускают почтовые программы только по отдельному паролю — передайте его в password.

Параметры

• Сервер — адрес[:порт]. Без схемы — TLS сразу, порт по умолчанию 993 для IMAP и 465 для SMTP. starttls:// — STARTTLS, порты по умолчанию 143 и 587.
• С since уведомлениями придут не больше 200 последних писем каждой отслеживаемой папки. Остальные читайте методом getMessages.

Пример запроса

Подключить ящик школы на Яндекс 360 — входом через сервис:

curl

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/connectMailbox/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "info@school.ru",
    "fromName": "Школа робототехники"
  }'

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/waInstance{os.environ['GRATIO_ID']}"
TOKEN = os.environ["GRATIO_TOKEN"]

url = f"{BASE}/connectMailbox/{TOKEN}"
payload = {"email": "info@school.ru", "fromName": "Школа робототехники"}
response = requests.post(url, json=payload, timeout=60)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/waInstance${GRATIO_ID}`;

const url = `${base}/connectMailbox/${GRATIO_TOKEN}`;
const payload = { email: "info@school.ru", fromName: "Школа робототехники" };
const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/waInstance' . getenv('GRATIO_ID');
$url = $base . '/connectMailbox/' . getenv('GRATIO_TOKEN');
$payload = ['email' => 'info@school.ru', 'fromName' => 'Школа робототехники'];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

Пример ответа

Ответ 200 OK — ссылка на страницу входа:

{
  "connected": false,
  "auth": "oauth",
  "email": "info@school.ru",
  "provider": "yandex",
  "providerTitle": "Яндекс",
  "authUrl": "https://oauth.yandex.ru/authorize?response_type=code&client_id=…",
  "expiresAt": 1791824858
}

Поля ответа

Что делать со ссылкой

Приложение             Gratio                     Сервис почты
    │ connectMailbox ────►│                             │
    │◄── authUrl ─────────│                             │
    │ человек открывает authUrl ───────────────────────►│ вход, «Разрешить»
    │                     │◄── возврат на страницу Gratio
    │                     │ проверка IMAP и SMTP        │
    │◄── stateInstanceChanged: authorized               │

1. Откройте authUrl человеку, который знает этот ящик, — в новом окне браузера.
2. Он входит в ящик email и разрешает доступ к почте. Пароль Gratio не видит.
3. Сервис возвращает его на страницу Gratio: ящик проверяется и подключается, окно можно закрыть.
4. Канал переходит в authorized — следите за getStateInstance или уведомлением stateInstanceChanged.

Ссылка одноразовая и действует 20 минут, до expiresAt. Человек отказал в доступе или вошёл не в тот ящик — итог показан на странице Gratio, а канал остаётся notAuthorized. Вызовите метод снова за новой ссылкой.

Ещё примеры

По паролю

Ящик на хостинге. Вход и отправка проверяются сразу, пароль сохраняется только после успешной проверки:

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/connectMailbox/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "info@school.ru",
    "password": "…",
    "since": "2026-10-01"
  }'

Ответ 200 OK — ящик подключён, канал сразу authorized:

{
  "connected": true,
  "auth": "password",
  "email": "info@school.ru",
  "login": "info@school.ru",
  "provider": "beget",
  "imap": {"host": "imap.beget.com", "port": 993, "security": "ssl"},
  "smtp": {"host": "smtp.beget.com", "port": 465, "security": "ssl"},
  "messages": 1532
}

Почта на своём сервере

Серверы заданы вручную — вход по паролю:

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/connectMailbox/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "info@school.ru",
    "password": "…",
    "imap": "mail.school.ru:993",
    "smtp": "starttls://mail.school.ru:587"
  }'

Как Gratio находит серверы

1. По домену адреса: yandex.ru, mail.ru, gmail.com, outlook.com, rambler.ru, icloud.com и другие домены этих сервисов.
2. По записи MX домена: почта компании на Яндекс 360, VK WorkMail, Google Workspace, Microsoft 365, RU-CENTER, Beget, Timeweb, REG.RU.
3. Иначе пробует imap.<домен> и mail.<домен>.

Не нашёл — servers_unreachable: задайте imap и smtp.

Ошибки

Не повторяйте запрос с тем же паролем после auth_failed: после серии неудачных входов сервис почты может заблокировать вход. Общие правила — в статье Ответы и ошибки.

Что дальше

• getStateInstance — дождаться authorized.
• getMailboxInfo — что подключилось: серверы, папки, квота.
• disconnectMailbox — отключить ящик.
• Почта — подключение ящика в кабинете.