eMail distribution via RESTful Interface
Der Versand von eMail kann kompliziert sein. Viele Faktoren müssen beachtet werden damit die versendete eMail nicht als “SPAM” markiert wird. Mit dem Release-Manager (RM) wird die Einrichtung von “DKIM”, “SPF” und “DMARC” mit PKI-Gesicherten eMails ein Kinderspiel.
Insbesondere wenn man automatisiert eMails versenden möchte, unterstützt der Release-Manager (RM) mit einem programmierbaren “REST-Interface”. Dazu muss einer eMail-Adresse nur das “REST-Interface” aktiviert werden. Aus Sicherheitsgründen muss das “REST-Interface” mit einem Client-Zertifikat angesprochen werden.
Es gibt noch ein paar weitere Besonderheiten für den Versand über das “REST-Interface”. Bitte beachten Sie bei Fehlermeldungen über das “REST-Interface” die beiliegende Tabelle für Fehlercodes.
Sollten Sie das REST-Interface mit Java ansprechen, finden Sie hier ein erstes Beispiel in Java:
Die Ergebnis-Codes helfen bei der korrekten Konfiguration. Sie sollten möglichst selbsterklärend sein.
| Code | Bereich | Erklärung | Maßnahmen |
|---|---|---|---|
| “DONE” | Versand | Die eMail wurde erfolgreich ausgeliefert und liegt im Posteingang des Empfängers. | |
| “MISSING_ANY_PERMISSION” | Sicherheit | Dem Client-Zertifikat gehört die eMail-Adresse nicht. | Erstellen Sie eine eMail-Adresse für den Besitzer des Client-Zertifikates. |
| “HAS_PERMISSION_BUT _MISSING_WHITELIST_ENTRY” | Sicherheit | Dem Client-Zertifikat gehört die eMail-Adresse aber es gibt keinen REST-Whitelist-Eintrag. | Erstellen Sie einen REST-Whitelist-Eintrag für die eMail-Adresse des Benutzers dem die .p12-Datei gehört (“example.p12” im Beispielcode) |
| “HAS_PERMISSION_HAS _WHITELIST_BUT_NONE _MATCH_NAME” | Sicherheit | Der Whitelist-Name (“GreetingWhitelist” im Beispielcode) passt nicht zum Whitelist-Namen. | Korrigieren Sie den Namen des REST-Whitelist-Eintrags. |
| “HAS_PERMISSION_HAS _WHITELIST_MATCH_NAME _BUT_IP_MISMATCH” | Sicherheit | Die IP-Adresse des Versenders passt zu keinem REST-Whitelist-Eintrag. | Korrigieren Sie die IP-Adresse des konfigurierten REST-Whitelist-Eintrags. Es sollte die IP-Adresse des Versenders sein. |
| “HAS_PERMISSION_HAS _WHITELIST_MATCH _NAME_MATCH_IP_AMBIGUOUS” | Sicherheit | Es gibt zu viele REST-Whitelist-Einträge für die IP. | Entfernen Sie doppelte REST-Whitelist-Einträge. |
| “RECIPIENTS_ADDRESS _MISS_AT_SIGN” | Validierung | Eine der Empfänger-eMail-Adressen fehlt das at-Zeichen (@). | Korrigieren Sie die Empfänger-eMail-Adressen im Code. |
| “RECIPIENTS_ADDRESS _MUST_BE_LOWCASE” | Validierung | Eine der Empfänger-eMail-Adressen hat ein Großbuchstaben. | Verwenden Sie ausschließlich eMail-Adressen die in Kleinbuchstaben geschrieben wurden. |
| “SUBJECT_IS_NOT _ALLOWED_TO _BE_EMPTY” | Validierung | Der Betreff der eMail ist leer. Das ist nicht erlaubt. | Korrigieren Sie die Betreff-Zeile der eMail. |
| “TEXT_OR_HTML _MUST_BE_SET” | Validierung | Sowohl der Text als auch der HTML-Code der eMail ist leer. Die eMail braucht aber einen Inhalt. | Korrigieren Sie HTML oder Text der eMail. |
| “ERROR_CHECK _MAIL_SEND_TRIAL” | Transport | Bei dem Versand der eMail an den Empfänger ist ein Fehler aufgetretten. | Details können Sie des Versandprotokolls der eMail entnehmen. |
| “HAS_PERMISSION _HAS_WHITELIST _MATCH_NAME _MATCH_IP_UNIQUE_BUT _SERVERHOSTNAME _MISMATCH” | Sicherheit | Der Server-Name des “REST-Whitelist-Interface” passt nicht zum Organisationsnamen in dem der Besitzer des Client-Zertifikats einer Benutzergruppe zugeordnet ist. | Prüfen Sie ob der Besitzer des Client-Zertifikats (“access.p12” im Beispielcode) in einer Benutzergruppe ist die der Organisation angehört die zum Hostnamen passt (“yourcompany.com” im Beispielcode). |
| “REQUEST_CONTENT _TYPE_MUST_BE_JSON” | Validierung | Der Typ der REST-Anfrage war kein “JSON”. | Geben Sie als “Content-Type” unbedingt “application/json” an! |
Hier der Beispielcode (Java):
String keystorePassword = "changeme";
String filename = "/home/applicationserver/access.p12";
String hostname = "yourcompany.com";
String whitelistName = "GreetingWhitelist";
KeyStore keyStore = KeyStore.getInstance("pkcs12");
keyStore.load(new FileInputStream(filename), keystorePassword.toCharArray());
KeyManagerFactory managerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
managerFactory.init(keyStore, keystorePassword.toCharArray());
SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(managerFactory.getKeyManagers(), null, null);
HttpClient http = HttpClient.newBuilder().sslContext(sslContext).build();
String json = """
{
"subject": "Greetings!",
"text": "Hello World!",
"html": "<b>Hello World!</b>",
"important": true,
"toAddresses": ["recipient@example.com"]
}""";
HttpRequest sendMailRequest = HttpRequest
.newBuilder(new URI("https://" + hostname + "/rest/mail/sendQueue/" + whitelistName))
.header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
.POST(HttpRequest.BodyPublishers.ofString(json)).build();
String result = http.send(sendMailRequest, HttpResponse.BodyHandlers.ofString()).body();
System.out.println(result); // will print {"code":"DONE"}Sending e-mails can be complicated. Many factors have to be taken into account so that the email sent is not marked as “SPAM”. With the Release Manager (RM), setting up “DKIM”, “SPF” and “DMARC” with PKI-secured e-mails is child’s play.
Especially if you want to send emails automatically, the Release Manager (RM) supports you with a programmable “REST interface”. All you have to do is activate the “REST interface” for an e-mail address. For security reasons, the “REST interface” must be addressed with a client certificate.
There are a few other special features for sending via the “REST interface”. Please refer to the enclosed table for error codes in the event of error messages via the “REST interface”.
If you are using Java to address the REST interface, you will find an initial example in Java here:
The result codes help with the correct configuration. They should be as self-explanatory as possible.
| Code | Range | Explanation | Measures |
|---|---|---|---|
| “DONE” | Dispatch | The email has been successfully delivered and is in the recipient’s inbox. | |
| “MISSING_ANY_PERMISSION” | Security | The client certificate does not own the email address. | Create an email address for the owner of the client certificate. |
| “HAS_PERMISSION_BUT _MISSING_WHITELIST_ENTRY” | Security | The client certificate owns the email address but there is no REST whitelist entry. | Create a REST whitelist entry for the email address of the user who owns the .p12 file (“example.p12” in the example code) |
| “HAS_PERMISSION_HAS _WHITELIST_BUT_NONE _MATCH_NAME” | Security | The whitelist name (“GreetingWhitelist” in the example code) does not match the whitelist name. | Correct the name of the REST whitelist entry. |
| “HAS_PERMISSION_HAS _WHITELIST_MATCH_NAME _BUT_IP_MISMATCH” | Security | The IP address of the sender does not match any REST whitelist entry. | Correct the IP address of the configured REST whitelist entry. It should be the IP address of the sender. |
| “HAS_PERMISSION_HAS _WHITELIST_MATCH _NAME_MATCH_IP_AMBIGUOUS” | Security | There are too many REST whitelist entries for the IP. | Remove duplicate REST whitelist entries. |
| “RECIPIENTS_ADDRESS _MISS_AT_SIGN” | Validation | One of the recipient email addresses is missing the at-sign (@). | Correct the recipient email addresses in the code. |
| “RECIPIENTS_ADDRESS _MUST_BE_LOWCASE” | Validation | One of the recipient e-mail addresses has a capital letter. | Only use e-mail addresses that are written in lower case. |
| “SUBJECT_IS_NOT _ALLOWED_TO _BE_EMPTY” | Validation | The subject of the e-mail is empty. This is not allowed. | Correct the subject line of the e-mail. |
| “TEXT_OR_HTML _MUST_BE_SET” | Validation | Both the text and the HTML code of the e-mail are empty. However, the e-mail needs content. | Correct the HTML or text of the e-mail. |
| “ERROR_CHECK _MAIL_SEND_TRIAL” | Transport | An error has occurred while sending the e-mail to the recipient. | Details can be found in the dispatch log of the e-mail. |
| “HAS_PERMISSION _HAS_WHITELIST _MATCH_NAME _MATCH_IP_UNIQUE_BUT _SERVERHOSTNAME _MISMATCH” | Security | The server name of the “REST-Whitelist-Interface” does not match the organization name in which the owner of the client certificate is assigned to a user group. | Check whether the owner of the client certificate (“access.p12” in the example code) is in a user group that belongs to the organization that matches the host name (“yourcompany.com” in the example code). |
| “REQUEST_CONTENT _TYPE_MUST_BE_JSON” | Validation | The type of the REST request was not “JSON”. | Be sure to specify “application/json” as the “Content-Type”! |
Here is the example code (Java):
L’envoi d’e-mails peut être compliqué. De nombreux facteurs doivent être pris en compte pour que l’e-mail envoyé ne soit pas marqué comme “SPAM”. Avec le Release-Manager (RM), la mise en place de “DKIM”, “SPF” et “DMARC” avec des e-mails sécurisés par PKI est un jeu d’enfant.
Le Release-Manager (RM) est doté d’une “interface REST” programmable, notamment pour l’envoi automatisé d’e-mails. Pour cela, il suffit d’activer l’interface REST d’une adresse e-mail. Pour des raisons de sécurité, l'”interface REST” doit être adressée avec un certificat client.
Il existe encore quelques particularités pour l’envoi via l'”interface REST”. En cas de messages d’erreur via l'”interface REST”, veuillez consulter le tableau des codes d’erreur ci-joint.
Si vous vous adressez à l’interface REST avec Java, vous trouverez ici un premier exemple en Java :
Les codes de résultat aident à la configuration correcte. Ils devraient être aussi explicites que possible.
| Code | Domaine | Explication | Mesures |
|---|---|---|---|
| “DONE” | Envoi | Le courriel a été livré avec succès et se trouve dans la boîte de réception du destinataire. | |
| “MISSING_ANY_PERMISSION” | Sécurité | Le certificat client n’est pas propriétaire de l’adresse e-mail. | Créez une adresse e-mail pour le propriétaire du certificat client. |
| “HAS_PERMISSION_BUT _MISSING_WHITELIST_ENTRY”. | Sécurité | Le certificat client possède l’adresse e-mail mais il n’y a pas d’entrée de liste blanche REST. | Créez une entrée de liste blanche REST pour l’adresse e-mail de l’utilisateur qui possède le fichier .p12 (“example.p12” dans l’exemple de code). |
| “HAS_PERMISSION_HAS _WHITELIST_BUT_NONE _MATCH_NAME” | Sécurité | Le nom de la liste blanche (“GreetingWhitelist” dans l’exemple de code) ne correspond pas au nom de la liste blanche. | Corrigez le nom de l’entrée de la liste blanche REST. |
| “HAS_PERMISSION_HAS _NOM_MATCH_DE_LA_WHITELIST _BUT_IP_MISMATCH” | Sécurité | L’adresse IP de l’expéditeur ne correspond à aucune entrée de liste blanche REST. | Corrigez l’adresse IP de l’entrée de liste blanche REST configurée. Il devrait s’agir de l’adresse IP de l’expéditeur. |
| “HAS_PERMISSION_HAS _WHITELIST_MATCH _NOM_MATCH_IP_AMBIGUOUS” | Sécurité | Il y a trop d’entrées de liste blanche REST pour l’IP. | Supprimez les entrées de liste blanche REST en double. |
| “RECIPIENTS_ADDRESS _MISS_AT_SIGN” | Validation | L’une des adresses e-mail des destinataires ne contient pas le caractère at (@). | Corrigez les adresses e-mail des destinataires dans le code. |
| “RECIPIENTS_ADDRESS _MUST_BE_LOWCASE” | Validation | L’une des adresses e-mail des destinataires est en majuscule. | Utilisez uniquement des adresses e-mail en minuscules. |
| “SUBJECT_IS_NOT” (LE SUJET N’EXISTE PAS) _ALLOWED_TO _BE_EMPTY” | Validation | Le sujet de l’e-mail est vide. Il n’est pas autorisé. | Corrigez la ligne d’objet de l’eMail. |
| “TEXT_OR_HTML _MUST_BE_SET”. | Validation | Le texte et le code HTML de l’e-mail sont vides. L’e-mail a pourtant besoin d’un contenu. | Corrigez le texte ou l’HTML de l’e-mail. |
| “ERROR_CHECK _MAIL_SEND_TRIAL”. | Transport | Une erreur s’est produite lors de l’envoi de l’e-mail au destinataire. | Vous trouverez des détails dans le protocole d’envoi de l’e-mail. |
| “HAS_PERMISSION _HAS_WHITELIST _MATCH_NAME _MATCH_IP_UNIQUE_BUT _NOM D’HÔTE DU SERVEUR _MISMATCH” | Sécurité | Le nom du serveur de l'”interface REST-Whitelist” ne correspond pas au nom de l’organisation dans laquelle le propriétaire du certificat client est affecté à un groupe d’utilisateurs. | Vérifier si le propriétaire du certificat client (“access.p12” dans l’exemple de code) fait partie d’un groupe d’utilisateurs appartenant à l’organisation correspondant au nom d’hôte (“yourcompany.com” dans l’exemple de code). |
| “REQUEST_CONTENT _TYPE_MUST_BE_JSON”. | Validation | Le type de la requête REST n’était pas “JSON”. | Indiquez impérativement “application/json” comme “Content-Type” ! |
Voici le code d’exemple (Java) :
Enviar correos electrónicos puede ser complicado. Hay que tener en cuenta muchos factores para que el correo electrónico enviado no se marque como “SPAM”. Con el Release Manager (RM), configurar “DKIM”, “SPF” y “DMARC” con correos electrónicos protegidos por PKI es un juego de niños.
Especialmente si desea enviar correos electrónicos automáticamente, el Gestor de versiones (RM) le ayuda con una “interfaz REST” programable. Todo lo que tiene que hacer es activar la “interfaz REST” para una dirección de correo electrónico. Por razones de seguridad, la “interfaz REST” debe dirigirse con un certificado de cliente.
Existen algunas otras características especiales para el envío a través de la “interfaz REST”. Consulte en la tabla adjunta los códigos de error en caso de mensajes de error a través de la “interfaz REST”.
Si utiliza Java para dirigirse a la interfaz REST, aquí encontrará un ejemplo inicial en Java:
Los códigos de resultado ayudan a la correcta configuración. Deben ser lo más autoexplicativos posible.
| Código | Alcance | Explicación | Medidas |
|---|---|---|---|
| “HECHO | Envío | El correo electrónico se ha enviado correctamente y se encuentra en la bandeja de entrada del destinatario. | |
| “MISSING_ANY_PERMISSION” | Seguridad | El certificado de cliente no es propietario de la dirección de correo electrónico. | Cree una dirección de correo electrónico para el propietario del certificado de cliente. |
| “HAS_PERMISSION_BUT FALTA_ENTRADA_EN_LISTA_BLANCA” | Seguridad | El certificado de cliente es propietario de la dirección de correo electrónico, pero no hay ninguna entrada en la lista blanca de REST. | Cree una entrada en la lista blanca de REST para la dirección de correo electrónico del usuario propietario del archivo .p12 (“ejemplo.p12” en el código de ejemplo) |
| “HAS_PERMISSION_HAS LISTA_BLANCA_PERO_NINGUNA MARCAR_NOMBRE” | Seguridad | El nombre de la lista blanca (“GreetingWhitelist” en el código de ejemplo) no coincide con el nombre de la lista blanca. | Corrija el nombre de la entrada REST de la lista blanca. |
| “HAS_PERMISSION_HAS NOMBRE_DE_LA_LISTA_BLANCA PERO_NO_COINCIDENCIA_IP” | Seguridad | La dirección IP del remitente no coincide con ninguna entrada de la lista blanca de REST. | Corrija la dirección IP de la entrada de la lista blanca de REST configurada. Debe ser la dirección IP del remitente. |
| “HAS_PERMISSION_HAS COINCIDENCIA_LISTA_BLANCA NOMBRE_COMPARACIÓN_IP_AMBIGUA” | Seguridad | Hay demasiadas entradas de lista blanca de REST para la IP. | Elimine las entradas duplicadas de la lista blanca de REST. |
| “RECIPIENTS_ADDRESS _MISS_AT_SIGN” | Validación | En una de las direcciones de correo electrónico de los destinatarios falta el símbolo de arroba (@). | Corrige las direcciones de correo electrónico de los destinatarios en el código. |
| “RECIPIENTS_ADDRESS _MUST_BE_LOWCASE” | Validación | Una de las direcciones de correo electrónico de los destinatarios está escrita en mayúsculas. | Utilice únicamente direcciones de correo electrónico escritas en minúsculas. |
| “SUBJECT_IS_NOT NO_SE_PERMITE_QUE ESTÉ_VACÍO” | Validación | El asunto del correo electrónico está vacío. No está permitido. | Corrija el asunto del correo electrónico. |
| “TEXT_OR_HTML DEBE_ESTABLECERSE” | Validación | Tanto el texto como el código HTML del correo electrónico están vacíos. Sin embargo, el correo electrónico necesita contenido. | Corrija el código HTML o el texto del mensaje. |
| “ERROR_CHECK _MAIL_SEND_TRIAL” | Transporte | Se ha producido un error al enviar el correo electrónico al destinatario. | Encontrará más detalles en el registro de envío del correo electrónico. |
| “HAS_PERMISSION _HAS_WHITELIST _MATCH_NAME _MATCH_IP_UNIQUE_BUT _SERVERHOSTNAME _MISMATCH” | Seguridad | El nombre del servidor de la “interfaz REST whitelist” no coincide con el nombre de la organización en la que el propietario del certificado de cliente está asignado a un grupo de usuarios. | Comprueba si el propietario del certificado de cliente (“access.p12” en el código de ejemplo) está en un grupo de usuarios que pertenece a la organización que coincide con el nombre del host (“tuempresa.com” en el código de ejemplo). |
| “REQUEST_CONTENT TYPE_MUST_BE_JSON” | Validación | El tipo de la solicitud REST no es “JSON”. | Asegúrese de especificar “application/json” como “Content-Type”. |
Aquí está el código de ejemplo (Java):
发送电子邮件可能很复杂。为了使发送的电子邮件不被标记为 “垃圾邮件”，必须考虑许多因素。有了发布管理器 (RM)，使用 PKI 安全电子邮件设置 “DKIM”、”SPF “和 “DMARC “就变得易如反掌。
特别是如果您想自动发送电子邮件，发布管理器 (RM) 还提供可编程的 “REST 接口”。您只需激活电子邮件地址的 “REST 接口 “即可。出于安全考虑，”REST 接口 “必须使用客户证书。
通过 “REST 接口 “发送邮件还有其他一些特殊功能。如果通过 “REST 接口 “发送错误信息，请参阅所附表格中的错误代码。
如果您使用 Java 来处理 REST 接口，您可以在这里找到 Java 的初始示例：
结果代码有助于正确配置。它们应尽可能不言自明。
| 代码 | 范围 | 说明 | 措施 |
|---|---|---|---|
| 完成 | 发送 | 邮件已成功发送，并已进入收件人收件箱。 | |
| “missing_any_permission”（缺少任何许可 | 安全性 | 客户证书不拥有电子邮件地址。 | 创建一个 电子邮件地址。 |
| “有权限，但 缺少白名单条目” _missing_whitelist_entry | 安全性 | 客户证书拥有电子邮件地址，但没有 REST 白名单条目。 | 为拥有 .p12 文件（示例代码中为 “example.p12″）的用户的电子邮件地址创建 REST 白名单条目 |
| “has_permission_has 但没有 _MATCH_NAME”。 | 安全 | 白名单名称（示例代码中的 “GreetingWhitelist”）与白名单名称不匹配。 | 更正 REST 白名单条目的名称。 |
| “has_permission_has 白名单匹配名称 _but_ip_mismatch”。 | 安全性 | 发件人的 IP 地址与任何 REST 白名单项不匹配。 | 更正已配置的 REST 白名单条目的 IP 地址。它应是发送方的 IP 地址。 |
| “有权限 白名单匹配 名称匹配 IP 地址不明确”。 | 安全性 | 该 IP 的 REST 白名单条目过多。 | 删除重复的 REST 白名单条目。 |
| “收件人地址 _MISS_AT_SIGN”（错过签收）。 | 验证 | 其中一个收件人电子邮件地址缺少 at-sign (@)。 | 更正代码中的收件人电子邮件地址。 |
| “收件人地址 必须小写” 验证 | 验证 | 收件人电子邮件地址中有一个大写字母。 | 只能使用小写的电子邮件地址。 |
| 主题 不允许 是空的” | 验证 | 电子邮件主题为空。这是不允许的。 | 更正电子邮件的主题行。 |
| “TEXT_OR_HTML _MUST_BE_SET”。 | 验证 | 电子邮件的文本和 HTML 代码都是空的。但是，电子邮件需要内容。 | 更正电子邮件的 HTML 或文本。 |
| “ERROR_CHECK（错误检查 邮件发送试验” | 传送 | 向收件人发送电子邮件时发生错误。 | 详情请查看电子邮件的发送日志。 |
| “有权限 邮件地址 _MATCH_NAME 但 服务器主机名 _MISMATCH” | 安全性 | REST 白名单接口 “的服务器名称与客户证书所有者被分配到用户组的组织名称不匹配。 | 检查客户证书所有者（示例代码中的 “access.p12″）所在的用户组是否属于与主机名匹配的组织（示例代码中的 “yourcompany.com”）。 |
| “请求内容 类型_must_be_json”。 | 验证 | REST 请求的类型不是 “JSON”。 | 请务必指定 “application/json “作为 “Content-Type”！ |
以下是示例代码（Java）：