eMail-RESTful-Gateway

Der Release-Manager (RM) kann für den automatischen Versand von eMail über REST eingerichtet werden. Ein gutes Beispiel dafür wäre das Versenden von Registrierungs-eMails oder Passwort-Vergessen-eMails ihrer Webapplikation.

Um automatisch eMails zu versenden muss dem eMail-Konto eine Whitelist-Freigabe erteilt werden für die IP-Adresse der Webapplikation.

In diesem Beispiel wurde dem Server mit der IP 192.0.2.0 der RESTful-Versand von eMails erlaubt. Um jetzt eine eMail über das REST-Interface zu senden, muss folgendes JSON zum Server gesendet werden:

Hat der Versand funktioniert bekommt der Empfänger die entsprechende eMail.

Beim Transport zum RESTful-Gateway müssen folgende Besonderheiten beachtet werden:

Der Transport zum RESTful-Gateway ist mit mTLS gesichert, es muss also das PKI-Benutzerzertifikat verwendet werden.
Der Name der Whitelist muss in die RESTful-Gateway-URL übergeben werden.
Der Benutzer, dem das PKI-Benutzerzertifikat gehört, darf nicht deaktiviert sein.
Die IP-Adresse der Whitelist muss mit der Quell-IP-Adresse des RESTful-Gateway-HTTPS-Requests übereinstimmen.
Die eMail-Adressen der Empfänger müssen Postfach-Mailbox-Adressen sein, Gruppen-Adressen sind nicht erlaubt.
Es darf nur genau eine Whitelist den Versand genehmigen.
Der Domänen-Teil der Versand-Adresse muss mit dem Host-Namen aus der RESTful-Gateway-URL und der TLD der Organisation des Benutzers überein stimmen.

Das RESTful-Gateway gibt folgende antworten:

1	*MISSING_ANY_PERMISSION*
2	*HAS_PERMISSION_BUT_MISSING_WHITELIST_ENTRY*
3	*HAS_PERMISSION_HAS_WHITELIST_BUT_NONE_MATCH_NAME*
4	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_BUT_IP_MISMATCH*
5	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_MATCH_IP_AMBIGUOUS*
6	*DONE*
7	*RECIPIENTS_ADDRESS_MISS_AT_SIGN*
8	*RECIPIENTS_ADDRESS_MUST_BE_LOWCASE*
9	*SUBJECT_IS_NOT_ALLOWED_TO_BE_EMPTY*
10	*TEXT_OR_HTML_MUST_BE_SET*
11	*ERROR_CHECK_MAIL_SEND_TRIAL*
12	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_MATCH_IP_UNIQUE_BUT_SERVERHOSTNAME_MISMATCH*
13	*REQUEST_CONTENT_TYPE_MUST_BE_JSON*

Im Erfolgsfall kommt der Rückgabewert “DONE” zurück. Das bedeutet dass die eMail versendet wurde und die eMail ist erfolgreich auf dem eMail-Service-Provider (eMSP) eingegangen. Aus technischen Gründen ist es nicht möglich heraus zu finden wie mit der eMail weiter verfahren wurde. Es ist möglich dass der Empfänger die eMail noch nicht im Posteingang sieht. Das liegt daran wie der eMail-Service-Provider (eMSP) die eMails verarbeitet. Der Release-Manager (RM) hat auf die internen Prozesse dort leider keine Einsicht.

The Release Manager (RM) can be set up to automatically send emails via REST. A good example of this would be sending registration emails or forgotten password emails from your web application.

To send emails automatically, the email account must be whitelisted for the IP address of the web application.

In this example, the server with the IP 192.0.2.0 has been allowed to send RESTful emails. To send an email via the REST interface, the following JSON must be sent to the server:

If the dispatch has worked, the recipient receives the corresponding email.

The following special features must be observed when transporting to the RESTful gateway:

The transport to the RESTful gateway is secured with mTLS, so the PKI user certificate must be used.
The name of the whitelist must be transferred to the RESTful gateway URL.
The user to whom the PKI user certificate belongs must not be deactivated.
The IP address of the whitelist must match the source IP address of the RESTful gateway HTTPS request.
The email addresses of the recipients must be mailbox addresses, group addresses are not permitted.
Only one whitelist may authorize the dispatch.
The domain part of the sending address must match the host name from the RESTful gateway URL and the TLD of the user’s organization.

The RESTful gateway gives the following answers:

1	*MISSING_ANY_PERMISSION*
2	*HAS_PERMISSION_BUT_MISSING_WHITELIST_ENTRY*
3	*HAS_PERMISSION_HAS_WHITELIST_BUT_NONE_MATCH_NAME*
4	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_BUT_IP_MISMATCH*
5	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_MATCH_IP_AMBIGUOUS*
6	*DONE*
7	*RECIPIENTS_ADDRESS_MISS_AT_SIGN*
8	*RECIPIENTS_ADDRESS_MUST_BE_LOWCASE*
9	*SUBJECT_IS_NOT_ALLOWED_TO_BE_EMPTY*
10	*TEXT_OR_HTML_MUST_BE_SET*
11	*ERROR_CHECK_MAIL_SEND_TRIAL*
12	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_MATCH_IP_UNIQUE_BUT_SERVERHOSTNAME_MISMATCH*
13	*REQUEST_CONTENT_TYPE_MUST_BE_JSON*

If successful, the return value “DONE” is returned. This means that the e-mail has been sent and the e-mail has been successfully received by the e-mail service provider (eMSP). For technical reasons, it is not possible to find out what happened to the e-mail. It is possible that the recipient does not yet see the email in their inbox. This is due to how the e-mail service provider (eMSP) processes the e-mails. Unfortunately, the release manager (RM) has no insight into the internal processes there.

Le gestionnaire de mise à jour (RM) peut être configuré pour l’envoi automatique d’e-mails via REST. Un bon exemple serait l’envoi d’e-mails d’enregistrement ou d’e-mails d’oubli de mot de passe de votre application web.

Pour envoyer automatiquement des e-mails, le compte de messagerie doit recevoir une autorisation de liste blanche pour l’adresse IP de l’application web.

Dans cet exemple, le serveur avec l’IP 192.0.2.0 a été autorisé à envoyer des e-mails par RESTful. Pour envoyer un e-mail via l’interface REST, le JSON suivant doit être envoyé au serveur :

Si l’envoi a fonctionné, le destinataire reçoit l’e-mail correspondant.

Lors du transport vers la passerelle RESTful, il faut tenir compte des particularités suivantes :

Le transport vers la passerelle RESTful est sécurisé par mTLS, il faut donc utiliser le certificat d’utilisateur PKI.
Le nom de la liste blanche doit être transmis dans l’URL de la passerelle RESTful.
L’utilisateur auquel appartient le certificat d’utilisateur PKI ne doit pas être désactivé.
L’adresse IP de la liste blanche doit correspondre à l’adresse IP source de la requête HTTPS de la passerelle RESTful.
Les adresses e-mail des destinataires doivent être des adresses de boîte aux lettres, les adresses de groupe ne sont pas autorisées.
Une seule liste blanche peut autoriser l’envoi.
La partie domaine de l’adresse d’envoi doit correspondre au nom d’hôte de l’URL de la passerelle RESTful et au TLD de l’organisation de l’utilisateur.

La passerelle RESTful Gateway donne les réponses suivantes :

1	*MISSING_ANY_PERMISSION*
2	*HAS_PERMISSION_BUT_MISSING_WHITELIST_ENTRY*
3	*HAS_PERMISSION_HAS_WHITELIST_BUT_NONE_MATCH_NAME*
4	*HAS_PERMISSION_HAS_WHITELIST_NOM_DE_CHOIX_BUT_IP_MISMATCH*
5	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_MATCH_IP_AMBIGUOUS*
6	*DONE*
7	*RECIPIENTS_ADDRESS_MISS_AT_SIGN*
8	*RECIPIENTS_ADDRESS_MUST_BE_LOWCASE*
9	*SUBJECT_IS_NOT_ALLOWED_TO_BE_EMPTY*
10	*TEXT_OR_HTML_MUST_BE_SET*
11	*ERROR_CHECK_MAIL_SEND_TRIAL*
12	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_MATCH_IP_UNIQUE_BUT_SERVERHOSTNAME_MISMATCH*
13	*REQUEST_CONTENT_TYPE_MUST_BE_JSON*

En cas de succès, la valeur de retour “DONE” est renvoyée. Cela signifie que l’email a été envoyé et qu’il est arrivé avec succès sur le fournisseur de services d’eMail (eMSP). Pour des raisons techniques, il n’est pas possible de savoir ce qu’il est advenu de l’e-mail. Il est possible que le destinataire ne voie pas encore l’e-mail dans sa boîte de réception. Cela est dû à la manière dont le fournisseur de services de messagerie (eMSP) traite les e-mails. Le gestionnaire de versions (RM) n’a malheureusement pas de vue sur les processus internes.

El Gestor de Ediciones (RM) puede configurarse para enviar automáticamente correos electrónicos a través de REST. Un buen ejemplo de esto sería el envío de correos electrónicos de registro o correos electrónicos de contraseñas olvidadas desde su aplicación web.

Para enviar correos electrónicos automáticamente, la cuenta de correo electrónico debe estar en la lista blanca para la dirección IP de la aplicación web.

En este ejemplo, el servidor con la IP 192.0.2.0 ha sido autorizado para enviar correos electrónicos RESTful. Para enviar un correo electrónico a través de la interfaz REST, debe enviarse al servidor el siguiente JSON:

Si el envío ha funcionado, el destinatario recibe el correo electrónico correspondiente.

Para el transporte a la pasarela RESTful deben tenerse en cuenta las siguientes particularidades:

El transporte a la pasarela RESTful está protegido con mTLS, por lo que debe utilizarse el certificado de usuario PKI.
El nombre de la lista blanca debe transferirse a la URL de la pasarela RESTful.
El usuario al que pertenece el certificado de usuario PKI no debe estar desactivado.
La dirección IP de la lista blanca debe coincidir con la dirección IP de origen de la solicitud HTTPS de la puerta de enlace RESTful.
Las direcciones de correo electrónico de los destinatarios deben ser direcciones de buzón, no se permiten direcciones de grupo.
Sólo una lista blanca puede autorizar el envío.
La parte de dominio de la dirección de envío debe coincidir con el nombre de host de la URL de la pasarela RESTful y el TLD de la organización del usuario.

La pasarela RESTful ofrece las siguientes respuestas:

1	*MISSING_ANY_PERMISSION*
2	*TIENE_PERMISO_PERO_FALTA_ENTRADA_EN_LISTA_BLANCA*
3	*HAS_PERMISSION_HAS_WHITELIST_BUT_NONE_MATCH_NAME (TIENE PERMISO PERO NO COINCIDE EL NOMBRE EN LA LISTA BLANCA)*
4	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_BUT_IP_MISMATCH*
5	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_MATCH_IP_AMBIGUOUS*
6	*DONE*
7	*RECIPIENTS_ADDRESS_MISS_AT_SIGN*
8	*RECIPIENTS_ADDRESS_MUST_BE_LOWCASE*
9	*SUBJECT_IS_NOT_ALLOWED_TO_BE_EMPTY*
10	*TEXT_OR_HTML_MUST_BE_SET*
11	*ERROR_CHECK_MAIL_SEND_TRIAL*
12	*HAS_PERMISSION_HAS_WHITELIST_MATCH_NAME_MATCH_IP_UNIQUE_BUT_SERVERHOSTNAME_MISMATCH*
13	*REQUEST_CONTENT_TYPE_MUST_BE_JSON*

Si tiene éxito, se devuelve el valor “DONE”. Esto significa que el correo electrónico se ha enviado y que el proveedor de servicios de correo electrónico (eMSP) lo ha recibido correctamente. Por razones técnicas, no es posible averiguar qué ha ocurrido con el correo electrónico. Es posible que el destinatario aún no vea el correo electrónico en su bandeja de entrada. Esto se debe a la forma en que el proveedor de servicios de correo electrónico (eMSP) procesa los correos electrónicos. Lamentablemente, el gestor de versiones (RM) no tiene conocimiento de los procesos internos que allí se llevan a cabo.

发布管理器 (RM) 可设置为通过 REST 自动发送电子邮件。从网络应用程序发送注册邮件或忘记密码邮件就是一个很好的例子。

要自动发送电子邮件，必须将电子邮件帐户列入网络应用程序 IP 地址的白名单。

在本例中，IP 地址为 192.0.2.0 的服务器已被授权发送 RESTful 电子邮件。要通过 REST 接口发送电子邮件，必须向服务器发送以下 JSON：

如果发送成功，收件人就会收到相应的电子邮件。

在向 RESTful 网关传输时，必须注意以下特殊功能：

到 RESTful 网关的传输使用 mTLS 加密，因此必须使用 PKI 用户证书。
白名单名称必须传输到 RESTful 网关 URL。
PKI 用户证书所属用户不得停用。
白名单的 IP 地址必须与 RESTful 网关 HTTPS 请求的源 IP 地址一致。
收件人的电子邮件地址必须是邮箱地址，不允许使用群组地址。
只有一个白名单可以授权发送。
发送地址的域名部分必须与 RESTful 网关 URL 中的主机名和用户组织的 TLD 相匹配。

RESTful 网关会给出以下响应：

1	*missing_any_permission*
2	*有权限但缺少白名单条目*
3	*has_permission_has_whitelist_but_none_match_name*
4	*has_permission_has_whitelist_match_name_but_ip_mismatch*
5	*has_permission_has_whitelist_match_name_match_ip_ambiguous*
6	完成
7	*收件人地址错过签名*
8	*收件人地址必须小写*
9	*主题不允许为空*
10	*text_or_html_must_be_set*
11	*error_check_mail_send_trial*
12	*has_permission_has_whitelist_match_name_match_unique_but_serverhostname_mismatch*
13	*request_content_type_must_be_json*

如果发送成功，则返回值为 “DONE”（完成）。这意味着电子邮件已发送，电子邮件服务提供商 (eMSP) 已成功接收电子邮件。由于技术原因，不可能知道电子邮件发生了什么。收件人有可能还没有在收件箱中看到电子邮件。这是由于电子邮件服务提供商 (eMSP) 处理电子邮件的方式造成的。不幸的是，发布经理 (RM) 无法深入了解其内部流程。