sendEmail

Отправляет письмо со всем, что есть в почтовой программе: несколько получателей, копия и скрытая копия, Reply-To, тема, текст и свой html, вложения, подпись, цитата, «ответить всем», отчёт о прочтении, важность, свои заголовки. Письмо уходит от адреса ящика, копия ложится в «Отправленные». Повтор с тем же clientMessageId второго письма не создаёт.

Параметры

* Нужен хотя бы один из message, html, files.

• Адреса в to, cc, bcc, replyTo — один адрес, список или строка через запятую.
• Новая тема в subject не начинает новую цепочку, если переписка с chatId уже идёт: письмо уйдёт ответом на её последнее письмо. Новая цепочка — newThread: true.
• Тема без текста, emailSubject и первой строки — «(без темы)». Первая строка длиннее 70 знаков обрезается по слову.

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

Расписание Марии и папе, копия — офису, новая цепочка:

curl

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/sendEmail/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatId": "maria@client.ru",
    "to": [
      "papa@client.ru"
    ],
    "cc": [
      "office@school.ru"
    ],
    "subject": "Расписание на ноябрь",
    "message": "Здравствуйте! Высылаем расписание занятий на ноябрь.",
    "files": [
      {
        "urlFile": "https://api.gratio.net/upload/7100000001/9b2e…/schedule.pdf",
        "fileName": "Расписание.pdf"
      }
    ],
    "newThread": true,
    "clientMessageId": "nov-schedule-maria"
  }'

Python

import os
import requests

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

url = f"{BASE}/sendEmail/{TOKEN}"
payload = {
    "chatId": "maria@client.ru",
    "to": ["papa@client.ru"],
    "cc": ["office@school.ru"],
    "subject": "Расписание на ноябрь",
    "message": "Здравствуйте! Высылаем расписание занятий на ноябрь.",
    "files": [
        {
            "urlFile": "https://api.gratio.net/upload/7100000001/9b2e…/schedule.pdf",
            "fileName": "Расписание.pdf",
        },
    ],
    "newThread": True,
    "clientMessageId": "nov-schedule-maria",
}
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}/sendEmail/${GRATIO_TOKEN}`;
const payload = {
  chatId: "maria@client.ru",
  to: ["papa@client.ru"],
  cc: ["office@school.ru"],
  subject: "Расписание на ноябрь",
  message: "Здравствуйте! Высылаем расписание занятий на ноябрь.",
  files: [
    {
      urlFile: "https://api.gratio.net/upload/7100000001/9b2e…/schedule.pdf",
      fileName: "Расписание.pdf",
    },
  ],
  newThread: true,
  clientMessageId: "nov-schedule-maria",
};
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 . '/sendEmail/' . getenv('GRATIO_TOKEN');
$payload = [
    'chatId' => 'maria@client.ru',
    'to' => ['papa@client.ru'],
    'cc' => ['office@school.ru'],
    'subject' => 'Расписание на ноябрь',
    'message' => 'Здравствуйте! Высылаем расписание занятий на ноябрь.',
    'files' => [
        [
            'urlFile' => 'https://api.gratio.net/upload/7100000001/9b2e…/schedule.pdf',
            'fileName' => 'Расписание.pdf',
        ],
    ],
    'newThread' => true,
    'clientMessageId' => 'nov-schedule-maria',
];

$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);

Файл сначала загрузите методом uploadFile — он вернёт urlFile.

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

Ответ 200 OK:

{
  "idMessage": "459f33988b5b2aa35d44",
  "emailMessageData": {
    "subject": "Расписание на ноябрь",
    "messageId": "gr.mcduelocvo27nud5klrpglrn3m@school.ru",
    "threadId": "459f33988b5b2aa35d44",
    "inReplyTo": null,
    "to": ["maria@client.ru", "papa@client.ru"],
    "cc": ["office@school.ru"],
    "bcc": [],
    "refused": {}
  }
}

Поля ответа

Если сервер отказал части получателей, ответ всё равно 200:

"refused": {"papa@client.ru": "550 5.1.1 Mailbox not found"}

Ещё примеры

Ответ в цепочку письма

На конкретное письмо Марии — всем, кто был в переписке:

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/sendEmail/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatId": "maria@client.ru",
    "quotedMessageId": "c62b698304229a98aad3",
    "message": "Мария, записали вас на субботу, 11:00.",
    "replyAll": true
  }'

Ответ на письмо из любой папки, без chatId, — replyEmail.

Свой html

Письмо со своей вёрсткой. message — текст для почтовых программ без html:

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/sendEmail/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatId": "maria@client.ru",
    "subject": "Итоги занятия",
    "message": "Сегодня собрали робота-сортировщика.",
    "html": "<h2>Итоги занятия</h2><p>Сегодня собрали <b>робота-сортировщика</b>.</p>",
    "newThread": true
  }'

Важное, с отчётом о прочтении

Высокая важность, отчёт о прочтении и свой заголовок для поиска:

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/sendEmail/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatId": "maria@client.ru",
    "subject": "Оплата за ноябрь",
    "message": "Напоминаем об оплате до 25 ноября.",
    "priority": "high",
    "readReceipt": true,
    "headers": {
      "X-Order": "1532"
    },
    "newThread": true
  }'

Получатель прочитал письмо и программа отправила отчёт — придёт outgoingMessageStatus со статусом read. Письма с заголовком найдёт searchMessages: {"folder": "sent", "header": {"X-Order": "1532"}}.

Что происходит после отправки

• Копия письма ложится в «Отправленные», если сервер не кладёт её сам. У копии тот же idMessage.
• Приходит уведомление о своём письме — см. Свои сообщения.
• Сервер получателя не принял письмо уже после отправки — он присылает отчёт, и приходит outgoingMessageStatus со статусом failed и причиной.
• Письма уходят не чаще одного в 2 секунды: следующий запрос подождёт.

Ошибки

Общие правила — в статье Ответы и ошибки.

Что дальше

• replyEmail — ответить на письмо из любой папки.
• saveDraft — сохранить письмо черновиком.
• outgoingMessageStatus — недоставка и отчёт о прочтении.
• Настройки ящика — подпись, имя отправителя и умолчания.