api.mail Обработка почты

Параметры входящих сообщений

  • Параметры получателей и отправителей обрабатываемого почтового сообщения (message):

    • message.getRecipientsAsString() — Список всех адресов получателей через символ ";"
    • message.getToAsString() — Список адресов получателей, указанных в поле "Кому" (TO);
    • message.getCcAsString() — Список адресов получателей, указанных в поле "Копия" (CC);
    • message.getCc() — Список получателей из адресов поля "Копия";
    • message.getFrom().getAddress() — Адрес отправителя сообщения;
    • message.getFrom().getName() — Имя отправителя сообщения;
    • message.getFrom().getDomain() — Домен отправителя сообщения (часть адреса после "@").

  • Получение параметров почтового сообщения (message):

    • message.getHeaders().get("название_заголовка") — Заголовок сообщения;
    • message.getSubject() — Тема сообщения;
    • message.getBody() — Тело сообщения как обычный текст;
    • message.getHtmlBody() — Тело сообщения в формате html, без обрамляющих тегов (<html> и <body> и др.) и потенциально опасных тегов;
    • message.getBodyRTF() — Тело сообщения в формате html, в котором ссылки на inline-вложения заменены на содержимое этих вложений;
    • message.getContentType() — Строка — тип содержимого;
    • message.getDigitalSignature() — Строка, соответствующая ЭЦП письма;
    • message.getInReplyTo() — Строка с идентификатором (Message-ID) родительского письма;
    • message.getPriority() — Строка, соответствующая приоритету письма;
    • message.getSize() — Размер письма в байтах;
    • message.getReplyTo() — Список строк-адресов для ответа.

  • message.getAttachments() — Список файлов, прикрепленных к письму.

  • Получение параметров вложения (attachment):

    • attachment.getFilename() — Имя файла (обычно короткое имя с расширением);
    • attachment.getContentType() — MIME-тип содержимого файла;
    • attachment.getData() — Массив байтов содержимого файла;
    • message.getAttachmentsTotalSize() — Суммарный размер вложений к письму message в байтах;
    • message.getInlineAttachments() — Список объектов-вложений, встроенных в тело в email сообщении message;
    • message.getNotInlineAttachments() — Список объектов-вложений, содержащихся в email-сообщении message.

Результаты обработки (result)

  • Параметры результатов обработки:

    • result.getMessageState() — статус сообщения;
    • result.isRejected() — факт отклонения письма: true — если письмо отклонено (rejected); false — в остальных случаях;
    • result.getRejectReason() — причина отклонения письма;
    • result.getRejectMessage() — текстовое описание причины отклонения;
    • result.isError() — факт наличия ошибки при обработке письма: true — если есть ошибка (error), false — в остальных случаях;
    • result.getErrorMessage() — текстовое описание ошибки при обработке письма;
    • result.error(errorMessage) — указание на то, что результатом является ошибка и назначение ее текстового описания.

  • result.setMessageState(messageState)

    Назначение статуса почтового сообщения.

    Параметр метода:

    • messageState — статус почтового сообщения.

    Возможные значения статуса:

    • api.mail.ERROR_MSG_STATE — обработка сообщения закончилась ошибкой;
    • api.mail.REJECT_MSG_STATE — сообщение было отклонено;
    • api.mail.NEW_BO_MSG_STATE — при обработке сообщения был создан новый бизнес-объект;
    • api.mail.ATTACH_MSG_STATE — обрабатываемое сообщение было прикреплено к существующему бизнес-объекту;
    • api.mail.OUTGOING_MSG_STATE — другое.

  • result.reject(reason)

    result.reject(reason, message)

    Отклонение письма с указанием причины.

    Параметры метода:

    • reason — причина отклонения;
    • messageState — статус почтового сообщения.

    Возможные причины отклонения:

    • api.mail.BAD_ATTACHMENTS_REJECT_REASON — к сообщению прикреплены несоответствующие вложения
    • api.mail.INVALID_EMAIL_REJECT_REASON — указан некорректный email-адрес;
    • api.mail.BIG_ATTACHMENT_REJECT_REASON — к сообщению прикреплено слишком большое вложение
    • api.mail.BAD_FORMAT_REJECT_REASON — несоответствующий формат сообщения
    • api.mail.CLIENT_NOT_FOUND_REJECT_REASON — не удалось определить клиента для запроса
    • api.mail.CONTACT_NOT_FOUND_REJECT_REASON — не удалось определить контактное лицо для запроса
    • api.mail.BLACKLIST_REJECT_REASON — входит в черный список
    • api.mail.OTHER_REJECT_REASON — другая причина.

  • result.isSuccessfull()

    Получение результата обработки входящего сообщения.

    Возвращаемое значение:

    • true — если письмо не отклонено (rejected) и не ошибка (error).
    • false — в других случаях.

Проверки входящих сообщений

  • api.mail.hasBadAttachment(message, acceptableExtensions, exceptableExtensions)

    Проверка допустимых и недопустимых типов вложений в сообщении. Данный метод не влияет на системную проверку наличия в письме недопустимых вложений с расширениями: "exe", "com", "bin". Если в письме есть хоть одно вложение с указанным расширением, то письмо будет отклонено.

    Параметры метода:

    • message — проверяемое сообщение
    • acceptableExtensions — список допустимых расширений файлов во вложении письма, может быть пуст
    • exceptableExtensions — список недопустимых расширений файлов во вложении письма, может быть пуст.

    Возвращаемое значение:

    • true — если в письме есть хоть одно вложение с недопустимым расширением
    • false — иначе

    Пример. Допустимые расширения файлов во вложении письма (скрипт правила обработки входящей почты):

    Copy 
    def acceptableExtensions = ['gif', 'jpg', 'png', 'htm', 'html', 'txt']; 
    //Недопустимые расширения файлов во вложении письма 
    def exceptableExtensions = ['exe', 'com', 'bin']; 
    if (api.mail.hasBadAttachment(message, acceptableExtensions, exceptableExtensions)) 
    { 
    logger.error('Входящее письмо содержит недопустимые файлы во вложении!'); 
    } 
    else 
    { 
    logger.info('Входящее письмо не содержит недопустимых файлов во вложении.'); 
    }

  • api.mail.isValidEmail(email)

    api.mail.helper.isValidEmail(email)

    Проверка email-адреса на корректность. Сравнение, поиск, изменение, удаление email-адресов производятся без учета регистра.

    email-адрес корректен, если

    • начинается только с буквы или цифры;
    • в FQDN (после @) используются только прописные от A до Z, строчные буквы от a до z; числа от 0 до 9; дефисы ( - )

    Для прохождения валидации внутренних доменов верхнего уровня необходимо указать эти домены в конфигурационном файле dbaccess.properties.

    Возвращаемое значение:

    • true — если email-адрес корректен.
    • false — если email-адрес не корректен.

  • api.mail.helper.isInvalidEmail(email)

    Проверка email-адреса на корректность. Сравнение, поиск, изменение, удаление email-адресов производятся без учета регистра.

    email-адрес корректен, если

    • начинается только с буквы или цифры;
    • в FQDN (после @) используются только прописные от A до Z, строчные буквы от a до z; числа от 0 до 9; дефисы ( - )

    Для прохождения валидации внутренних доменов верхнего уровня необходимо указать эти домены в конфигурационном файле dbaccess.properties.

    Возвращаемое значение:

    • null, если email-адрес корректен;
    • сообщение об ошибке, если email-адрес не корректен.

  • api.mail.helper.isSystemEmailAddress(email)

    Проверка email-адреса на принадлежность к email-адресу системы. В сообщениях, отправляемых системой, в поле "from" указан email-адрес системы, который задан в настройке исходящей почты.

    Возвращаемое значение:

    • true — если проверяемый email-адрес является email-адресом системы (сообщения, отправляемые системой, имеют from с указанным адресом).
    • false — иначе.

  • api.mail.helper.getFeedbackAddress()

    Возвращает строку — адрес службы технической поддержки.

  • api.mail.helper.getInboundMailAddresses()

    Получение списка логинов подключения к почтовым серверам, на которые настроена обработка входящей почты.

Прикрепление входящих сообщений к объекту

  • api.mail.attachMessage(subject, message)

    api.mail.helper.attachMessage(subject, message) (УСТАРЕВШИЙ)

    Прикрепление входящего сообщения к объекту.

    Параметры метода:

    • subject — объект, к которому прикрепляется сообщение;
    • message — входящее сообщение.

    Результат выполнения: входящее сообщение прикрепляется как файл .eml, для просмотра файла используется почтовый клиент.

  • api.mail.attachMessageAttachments(subject, message)

    api.mail.helper.attachMessageAttachments(subject, message) (УСТАРЕВШИЙ)

    Прикрепление вложений из входящего сообщения к объекту, кроме изображений, вложенных в текст письма.

    Параметры метода:

    • subject — объект, к которому прикрепляются вложения письма;
    • message — входящее сообщение.

  • api.mail.attachAllMessageAttachments(subject, message)

    Прикрепление вложений из входящего сообщения к объекту, включая изображения, вложенные в текст письма. Само входящее сообщение не прикрепляется.

    Параметры метода:

    • subject — объект, к атрибуту которого прикрепляются вложения и изображения из письма;
    • message — входящее сообщение.

  • api.mail.attachMessageAttachments(subject, message, attrCode)

    Прикрепление вложений из входящего сообщения к определенному атрибуту объекта, кроме изображений, вложенных в текст письма.

    Параметры метода:

    • subject — объект, к атрибуту которого прикрепляются вложения письма;
    • message — входящее сообщение;
    • attrCode — атрибут объекта, к которому прикрепляются вложения письма.

Модификация входящих сообщений

  • api.mail.helper.replaceReferencesToAttachments(message)

    Модификация html содержимого письма с целью корректного отображения содержимого по ссылкам (например, вложенные картинки).

    Преобразует содержание письма в формате HTML: заменяет ссылки на составные части письма (например, содержимое картинки) ссылками на прикрепленные файлы.

    Данный метод следует использовать после прикрепления всех вложений входящего сообщения message к объекту subject:

    api.mail.helper.attachMessageAttachments(subject, message)

  • api.mail.helper.correctFileName(name)

    Замена запрещенных для windows/linux символов в именах файлов.

    Параметр метода:

    • name — имя файла. String.

    Возвращает имя файла, в котором все запрещенные символы заменены знаком подчеркивания.

Получение информации из письма

  • api.mail.getCallNumber(messageTheme)

    Получение номера запроса из темы письма. Метод ищет номер как слово (т.е. последовательность цифр, отделенная разделителями, например, "запрос 1 создан"). Если ничего не найдено, ищет последовательность цифр в строке (например, "запрос №1 создан").

    Параметр метода:

    • messageTheme — тема письма в скрипте обработки почты IInboundMailMessage.

    Возвращает номер запроса из темы письма.

  • api.mail.getNumberWithPrefix(messageTheme, prefix)

    Получение номера запроса из темы письма, после определенного префикса и пробела.

    Параметры метода:

    • messageTheme — тема письма. String;
    • prefix — префикс номера. String.

    Возвращает номер запроса.

  • api.mail.getNumberWithPrefix(messageTheme, prefix, existSpaceAfterPrefix)

    Получение номера запроса из темы письма, после определенного префикса.

    Параметры метода:

    • messageTheme — тема письма. String;
    • prefix — префикс номера. String;
    • existSpaceAfterPrefix — true (есть пробел между префиксом и номером), false (пробела нет).

    Возвращает номер запроса.

Поиск запроса

  • api.mail.helper.searchSCByNumber(callId)

    Поиск запроса по номеру.

    Параметр метода:

    • callId — номер запроса. String.

    Возвращает запрос.

  • api.mail.searchByCallNumber(message)

    Поиск запроса по номеру из письма.

    Параметр метода:

    • message — входящее сообщение.

    Возвращает запрос.

  • api.mail.searchByCallNumberWithPrefix(message, prefix)

    Поиск запроса по номеру из письма с префиксом.

    Параметры метода:

    • message — входящее сообщение;
    • prefix — префикс номера. String.

    Возвращает объект-запрос по его номеру.

  • api.mail.helper.searchByCallTitle(subject)

    Поиск запроса по названию.

    Возвращает первый запрос с таким названием или null, если нет запросов с таким именем.

Поиск сотрудника

  • api.mail.searchEmployeeByEmail(email)

    api.mail.helper.searchEmployeeByEmail(email)

    Поиск сотрудника по email-адресу.

    Возвращаемое значение:

    • сотрудник — если найден только один сотрудник;
    • null — если не найдено ни одного сотрудника или найдено два сотрудника с одинаковым email;
    • генерирует исключение — если найдено более одного сотрудника.

  • api.mail.searchEmployeesByEmail(email)

    Поиск всех сотрудников с указанному email.

    Возвращает список неархивных сотрудников с указанным email.

  • api.mail.helper.findEmployeesByEmail(email, type)

    Поиск всех сотрудников указанного типа с указанным email.

    Параметры метода:

    • email — email адрес сотрудника;
    • type — тип сотрудников.

  • api.mail.searchEmployeeByLastName(lastName)

    Поиск сотрудника по фамилии.

    Возвращает неархивного сотрудника с указанной фамилией. Если существует несколько сотрудников с одинаковой фамилией вернется null.

Генерация события "Поступление письма"

  • api.mail.helper.notifyMailReceived(scall)

    Генерация события "Поступление письма":

Формирование тела обратного письма

При использовании методов respondBody письмо загружается целиком в память и потенциально может возникнуть нехватка памяти.

  • api.mail.formRespondBody(processingResult)

    Формирование тела обратного письма с пометкой об отклонении обработки входящего письма, а также указанием причины отклонения (если она есть).

    Параметр метода:

    • processingResult — результат обработки входящего письма.

    Возвращает сформированное тело письма в виде строки.

    Пример:

    def respondBody = api.mail.formRespondBody(result);

  • api.mail.respondBody(message)

    Формирование тела обратного письма с цитированием исходного сообщения.

    Параметр метода:

    • message — исходное входящее сообщение.

    Возвращает сформированное тело письма в виде строки.

    Пример:

    def respondBody = api.mail.respondBody(message)