Команда sendMail — описание и примеры

Команда sendMail позволяет создать новое электронное письмо (черновик) в КриптоАРМ с переданными параметрами: получатели, тема, содержимое, вложения, флаги подписи и шифрования.

Содержание:

• Команда sendMail — описание и примеры
• Общая информация
• Формат ссылки
• Получение параметров операции
  • Формат запроса (удалённый режим)
  • Формат ответа
• Отправка статуса
  • Формат запроса статуса
• Справочник интерфейсов
  • Интерфейс IMailProps
  • Параметры лицензии и подписи
• Интерфейс приложения

---

Общая информация

Команда sendMail используется для создания нового черновика электронного письма в КриптоАРМ с переданными параметрами. После заполнения и отправки письма пользователем, КриптоАРМ уведомляет сервер о статусе операции.

Схема взаимодействия:

Все запросы между КриптоАРМ и сервером ДОЛЖНЫ соответствовать спецификации протокола JSON-RPC 2.0.

В качестве транспорта используется HTTP.

🔍 Общее описание указано в разделе Формат ссылки.

---

Формат ссылки

Для выполнения команды sendMail должна быть сформирована ссылка вида:

cryptoarm://sendMail/<URL>/?id=<id>[&authType=<authType>]

• cryptoarm:// - зарегистрированный протокол
• sendMail - выполняемая команда
• <URL> - ссылка, на которую КриптоАРМ будет слать запросы
• id - уникальный идентификатор транзакции
• authType - необязательный параметр. Тип аутентификации.

Пример:

cryptoarm://sendMail/https://example.com/json?id=2c48eb32-a0a8-405c-ade9-eed130605cba

Локальный режим: При использовании через локальное API (file:// или встроенный JSON), paramsJson должен содержать непосредственно объект IMailOperationProps (см. ниже).

---

Получение параметров операции

После получения команды sendMail КриптоАРМ отправляет запрос на получение параметров операции.

Формат запроса (удалённый режим)

Ключ	Значение	Описание
jsonrpc	«2.0»	Версия JSON-RPC протокола. Всегда «2.0».
method	sendMail.parameters	Используемый метод. Всегда sendMail.parameters.
id	Уникальный идентификатор	Используется идентификатор, который указан в ссылке на операцию.
diagnostic	IDiagnosticsInformation	Диагностическая информация о рабочем месте. Содержит поля VERSIONS, PROVIDERS, LICENSES.

Пример:

Content-Type: application/json
Content-Length: ...
Accept: application/json
{
    "jsonrpc": "2.0",
    "method": "sendMail.parameters",
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba",
    "diagnostic": {
      "VERSIONS": { "csp": "5.0.11753", "cryptoarm": "2.5.2", "openssl": "1.1.1w" },
      "PROVIDERS": { "GOST2012_256": true, "GOST2012_512": true, "openssl": true },
      "LICENSES": {
        "csp": { "status": true, "type": "", "expiration": "" },
        "cryptoarm": { "status": true, "type": "Permanent", "expiration": "" }
      }
    }
}

Формат ответа

Ключ	Значение	Описание
jsonrpc	«2.0»	Версия JSON-RPC протокола. Всегда «2.0».
result	{ props: { mailProps: IMailProps } }	Объект со свойствами письма
id	Уникальный идентификатор	Используется идентификатор, который указан в ссылке на операцию.

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

HTTP/1.1 200 OK
Connection: close
Content-Length: ...
Content-Type: application/json
Date: Sat, 08 Jul 2020 12:04:08 GMT
{
    "jsonrpc": "2.0",
    "result": {
        "props": {
            "mailProps": {
               "to": ["test@example.com"],
               "cc": ["test1@example.com", "test2@example.com"],
               "bcc": ["test3@example.com"],
               "subject": "Message subject",
               "content": "text message content",
               "htmlContent": "<div>HTML message content</div>",
               "attachments": [
                   {
                       "name": "file1.txt",
                       "url": "http://localhost:8080/public/files/file1.txt",
                       "id": "1",
                       "urlDetached": ""
                   },
                   {
                       "name": "file2.txt",
                       "url": "http://localhost:8080/public/files/file2.txt",
                       "id": "2",
                       "urlDetached": ""
                   }
               ],
               "sign": false,
               "encrypt": false,
               "deliveryReport": false,
               "readReport": false
            }
        }
    },
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba"
}

---

Отправка статуса

После того как пользователь отправит письмо или закроет окно, КриптоАРМ отправляет статус операции на сервер.

Формат запроса статуса

Ключ	Значение	Описание
jsonrpc	«2.0»	Версия JSON-RPC протокола. Всегда «2.0».
method	sendMail.status	Используемый метод.
params	{ id, status }	Параметры статуса

Параметр	Тип	Описание
id	string	Идентификатор транзакции
status	string	Статус: "success" (письмо отправлено) или "canceled" (отменено)

Пример:

Content-Type: application/json
Content-Length: ...
Accept: application/json
{
    "jsonrpc": "2.0",
    "method": "sendMail.status",
    "params": {
        "id": "2c48eb32-a0a8-405c-ade9-eed130605cba",
        "status": "success"
    }
}

---

Справочник интерфейсов

Интерфейс IMailProps

Объекты данного типа описывают параметры электронного сообщения.

Свойство	Тип	Описание
to	string[]	Массив адресов получателей
cc?	string[]	Массив адресов получателей копии
bcc?	string[]	Массив адресов получателей скрытой копии
subject	string	Тема сообщения
content	string	Текстовое содержимое сообщения
htmlContent?	string	Форматированное содержимое сообщения в формате HTML
attachments?	IFile[]	Файлы для прикрепления к сообщению (вложения). Скачиваются КриптоАРМ перед открытием окна письма.
sign	boolean	Флаг, указывающий на необходимость подписать сообщение
encrypt	boolean	Флаг, указывающий на необходимость зашифровать сообщение
deliveryReport	boolean	Флаг, включающий получение отчета о доставке
readReport	boolean	Флаг, включающий получение отчета о прочтении

Параметры лицензии и подписи

Свойство	Тип	Описание
license?	string	Необязательный параметр. Временная лицензия для выполнения операции (добавляется на время сессии).

---

Интерфейс приложения

При выполнении команды sendMail открывается окно создания нового сообщения с предзаполненными полями: получатели, тема, содержимое, вложения. Если передан флаг sign, включается подпись сообщения. Если передан флаг encrypt, включается шифрование.

Пользователь может отредактировать письмо, выбрать сертификаты для подписи/шифрования и отправить его или отменить операцию. После закрытия окна КриптоАРМ отправляет статус (success или canceled) на сервер.

Предыдущая

Следующая