Документация Email API

Создание API ключа

Создание API ключа доступно по ссылке: https://beta.rusender.ru/api.

Подробную информацию о создании API ключа можно прочитать в нашей Базе знаний.

Важно: тестовые письма необходимо слать только на существующие email адреса, иначе ключ будет забанен.

Роут отправки письма (с готовым HTML)

POST https://api.beta.rusender.ru/api/v1/external-mails/send

В заголовке «X-Api-Key» необходимо передать строкой ключ API для аутентификации.

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

{
   "idempotencyKey": "unique-key-string",
   "mail": {
        "to": {
            "email": "user@example.com",
            "name": "string"
        },
        "from": {
             "email": "user@example.com",
             "name": "string"
        },
        "subject": "string",
        "previewTitle": "string",
        "headers": {
        },
        "cc": "string",
        "bcc": "string",
        "html": "string",
        "text": "string"
   }
}

Описание полей

• subject* (тема) — содержит тему или заголовок письма;

• previewTitle — прехедер письма, до 120 символов;

• html*, text — если передать и текстовую и HTML-версию одновременно, то клиент почты получателя будет решать, какую версию отобразить пользователю в зависимости от его настроек и возможностей. Обычно почтовые клиенты отображают в формате HTML, если они поддерживают эту функцию. Наш сервис автоматически генерирует text похожий на html, если text не передан (или передана пустая строка);

• name (to/from) — имя получателя/отправителя письма;

• headers — системные заголовки письма (необязательно поле, для опытных пользователей) https://nodemailer.com/message/custom-headers;

• cc и bcc — это адрес получателя копии и адрес получателя скрытой копии;

  • cc (Carbon Copy) — это поле «копия» или «отправить копию». Адресат указанный в CC получит копию сообщения, но все получатели смогут видеть, кому еще были отправлены копии сообщения;

  • bcc (Blind Carbon Copy) — это поле «скрытая копия». Это может быть полезно, если вы хотите отправить копию сообщения кому-то без раскрытия его адреса другим адресатам.

• attachments — вложение в письмо (файл), в формате массива файлов структурой вида:

  { "название файла.расширение": "тело файла закодированное в base64"};

• idempotencyKey (String) — ключ идемпотентности используется для предотвращения повторного выполнения одного и того же запроса.

  Отправка с использованием ключа идемпотентности

  По умолчанию, если в течение одного часа поступает запрос на отправку письма с полностью совпадающими параметрами:

  • отправитель (From);
  • получатель (To);
  • тело письма (Body).

  Такой запрос будет отклонён для предотвращения задвоения писем.

  Если требуется отправка писем с одинаковыми параметрами (например, уведомление «Ваш комментарий одобрен»), необходимо использовать кастомный ключ идемпотентности «idempotencyKey», который должен быть передан вне блока «mail» в запросе. При различающемся «idempotencyKey» письма будут считаться разными и будут успешно отправлены.

Примечания

• Кодировку указать нельзя, всегда используется UTF-8;

• Запрос принимает любые системные заголовки, но те которые проставляются нами — имеют приоритет, а именно: Return-Path, List-Unsubscribe, Errors-To, X-Complaints-To, Precedence, Feedback-ID, X-SenderName-MailID, X-Mailru-Msgtype, X-Postmaster-Msgtype.

Возможные ответы

{
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
    "message": "mail.to.name must be shorter than or equal to 255 characters,mail.from.email must be an email",
    "statusCode": 400
}

{
    "message": "Неверный ключ API",
    "statusCode": 401
}

$headers = array(
   'Content-Type: application/json',
   'X-Api-Key: YOUR_API_KEY'
);

Ограничения по прикрепляемым файлам и размеру

Примеры использования API

• PHP
• Python
• Node.js
• JavaScript

$url = 'https://api.beta.rusender.ru/api/v1/external-mails/send';
$data = array(
   'idempotencyKey' => 'unique-key-string',
   'mail' => array(
       'to' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'from' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'subject' => 'string',
       'previewTitle' => 'string',
       'html' => 'string'
   )
);
$headers = array(
   'Content-Type' => 'application/json',
   'X-Api-Key' => 'YOUR_API_KEY'
);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

import requests
import json
url = 'https://api.beta.rusender.ru/api/v1/external-mails/send'
data = {
    'idempotencyKey': 'unique-key-string',
    'mail': {
        'to': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'from': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'subject': 'string',
        'previewTitle': 'string',
        'html': 'string'
    }
}
headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
}
response = requests.post(url, json=data, headers=headers)

const axios = require('axios');
const url = 'https://api.beta.rusender.ru/api/v1/external-mails/send';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name : 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        html: 'string'
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};
axios.post(url, data, { headers })
    .then(response => {
        // Обработка ответа API
    })
    .catch(error => {
        // Обработка ошибки
    });

const url = 'https://api.beta.rusender.ru/api/v1/external-mails/send';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        html: 'string'
        }
    };
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};
fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
    .then(response => response.json())
    .then(data => {
        // Обработка ответа API
    })
    .catch(error => {
        // Обработка ошибки
    });

Отправка письма с использованием шаблона RuSender

POST 'https://api.beta.rusender.ru/api/v1/external-mails/send-by-template';

В заголовке «X-Api-Key» передать строкой ключ API для аутентификации.

Запрос идентичен обычной отправки письма по API за исключением тела письма (тело не имеет html и text, однако имеет idTemplateMailUser и params).

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

{
   "idempotencyKey": "unique-key-string",
   "mail": {
        "to": {
            "email": "user@example.com",
            "name": "string"
        },
        "from": {
             "email": "user@example.com",
             "name": "string"
        },
        "subject": "string",
        "previewTitle": "string",
        "idTemplateMailUser": number,
        "params": {
             "test": "string",
             "test1": "string",
             "test2": "string"
        }
   }
}

Описание полей

• from* (От) — адрес отправителя письма;

• to* (Кому) — адрес получателя письма;

• subject* (Тема) — содержит тему или заголовок письма;

• previewTitle — прехедер письма, до 120 символов;

• idTemplateMailUser — id шаблона из раздела "Мои шаблоны", примечание: Шаблоны из раздела "Галерея" работать не будут;

• cc и bcc — это адрес получателя копии и адрес получателя скрытой копии;

  • cc (Carbon Copy) — это поле "копия" или "отправить копию". Адресат указанный в CC получит копию сообщения, но все получатели смогут видеть смогут видеть, кому еще были отправлены копии сообщения;

  • bcc (Blind Carbon Copy) — это поле "скрытая копия". Это может быть полезно, если вы хотите отправить копию сообщения кому-то без раскрытия его адреса другим адресатам.

• params — кастомные переменные для вставки в шаблон;

• headers — системные заголовки письма (необязательно поле, для опытных пользователей) https://nodemailer.com/message/custom-headers/;

  Принимаем любые системные заголовки, но те которые проставляются нами - имеют приоритет, а именно:

  Return-Path, List-Unsubscribe, Errors-To, X-Complaints-To, Precedence, Feedback-ID, X-SenderName-MailID, X-Mailru-Msgtype, X-Postmaster-Msgtype.

  Кодировку указать нельзя, всегда используется UTF-8.

• attachments — вложение в письмо (файл), в формате массива файлов структурой вида:

  { "название файла.расширение": "тело файла закодированное в base64"};

• idempotencyKey (String) — ключ идемпотентности используется для предотвращения повторного выполнения одного и того же запроса.

  Отправка с использованием ключа идемпотентности

  По умолчанию, если в течение одного часа поступает запрос на отправку письма с полностью совпадающими параметрами:

  • отправитель (From);
  • получатель (To);
  • тело письма (Body).

  Такой запрос будет отклонён для предотвращения задвоения писем.

  Если требуется отправка писем с одинаковыми параметрами (например, уведомление «Ваш комментарий одобрен»), необходимо использовать кастомный ключ идемпотентности «idempotencyKey», который должен быть передан вне блока «mail» в запросе. При различающемся «idempotencyKey» письма будут считаться разными и будут успешно отправлены.

Примеры использования API с шаблоном письма RuSender

• PHP
• Python
• Node.js
• JavaScript

$url = 'https://api.beta.rusender.ru/api/v1/external-mails/send-by-template';
$data = array(
   'idempotencyKey' => 'unique-key-string',
   'mail' => array(
       'to' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'from' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'subject' => 'string',
       'previewTitle' => 'string',
       'idTemplateMailUser' => number,
       'params' => array(
           'test' => 'string',
           'test1' => 'string',
           'test2' => 'string'
       )
   )
);
$headers = array(
   'Content-Type' => 'application/json',
   'X-Api-Key' => 'YOUR_API_KEY'
);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

import requests
import json
url = 'https://api.beta.rusender.ru/api/v1/external-mails/send-by-template'
data = {
    'idempotencyKey': 'unique-key-string',
    'mail': {
        'to': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'from': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'subject': 'string',
        'previewTitle': 'string',
        'idTemplateMailUser': number,
        'params': {
            'test': 'string',
            'test1': 'string',
            'test2': 'string'
        }
    }
}
headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
}
response = requests.post(url, json=data, headers=headers)

const axios = require('axios');
const url = 'https://api.beta.rusender.ru/api/v1/external-mails/send-by-template';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        idTemplateMailUser: number,
        params: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};
axios.post(url, data, { headers })
    .then(response => {
        // Обработка ответа API
    })
    .catch(error => {
        // Обработка ошибки
    });

const url = 'https://api.beta.rusender.ru/api/v1/external-mails/send-by-template';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        idTemplateMailUser: number,
        params: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};
fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
    .then(response => response.json())
    .then(data => {
        // Обработка ответа API
    })
    .catch(error => {
        // Обработка ошибки
    });