Envoyer en SMTP
Le même envoi que POST /emails, pour les logiciels qui parlent SMTP.
Se connecter
Tout ce qui envoie du courrier par un serveur SMTP peut envoyer par OpenEmail : le mailer d'un framework, un CMS, un outil de supervision, une imprimante. Connectez-vous avec le nom d'utilisateur openemail et une clé API comme mot de passe. La clé doit avoir la portée emails:send, et un message qu'elle transmet est le même envoi que POST /emails fait avec cette clé.
| Paramètre | Valeur |
|---|---|
| Hôte | smtp.openemail.uk |
| Port | 465 avec SSL/TLS, ou 587 avec STARTTLS |
| Nom d'utilisateur | openemail |
| Mot de passe | Une clé API avec la portée emails:send |
| Connexion | PLAIN ou LOGIN, que la plupart des logiciels appellent un mot de passe normal |
Rien n'est accepté en clair, et sur le port 587 la connexion au compte ne s'ouvre qu'après STARTTLS. Une clé API ne se connecte que pour envoyer. Lire une boîte mail en IMAP ou POP3 demande un mot de passe d'application.
Envoyer un message de test
Enregistrez un message sous message.eml et transmettez-le avec curl. From doit être une adresse au nom de laquelle la clé peut envoyer.
From: Acme <[email protected]>To: [email protected]Subject: Hello over SMTPMessage-ID: <[email protected]> It works.curl --url "smtps://smtp.openemail.uk:465" \ --user "openemail:$OPENEMAIL_API_KEY" \ --mail-from "[email protected]" \ --mail-rcpt "[email protected]" \ --upload-file message.eml --crlfcurl --ssl-reqd --url "smtp://smtp.openemail.uk:587" \ --user "openemail:$OPENEMAIL_API_KEY" \ --mail-from "[email protected]" \ --mail-rcpt "[email protected]" \ --upload-file message.eml --crlfLa réponse à un message accepté est 250 2.0.0 OK queued as suivi de son id. Cet id est celui que prend GET /emails/{id}, si bien que le message, ses événements et son suivi se lisent comme ceux de n'importe quel autre envoi.
Comment un message devient un envoi
Le message est lu puis envoyé par le même chemin qu'un envoi REST, il est donc reconstruit à partir de ses parties et non retransmis octet par octet.
| Dans le message | Dans l'envoi |
|---|---|
| From | from. Il est obligatoire, et c'est l'expéditeur par rapport auquel la clé est vérifiée. L'adresse dans MAIL FROM doit seulement être présente. |
| RCPT TO | À qui le message est remis, 50 au plus. Un destinataire nommé dans To est un to, un destinataire nommé dans Cc est un cc, et un destinataire nommé dans aucun des deux est un bcc. Au moins un doit figurer dans To. |
| Reply-To | replyTo, la première adresse. |
| Subject | subject. |
| Les parties texte et HTML | text et html. Une image que le HTML utilise comme cid: est insérée là où elle apparaît. |
| Pièces jointes | attachments : 20 fichiers au plus et 5 Mo en tout. |
| Autres en-têtes | X-*, List-*, Precedence, Auto-Submitted, Importance, Priority et Feedback-ID sont conservés. Tout autre en-tête est omis. |
| X-OpenEmail-Stream | stream : transactional ou broadcast. L'en-tête est retiré avant que le message ne parte. |
Ce qui s'applique
Tout ce qui s'impose à un envoi REST s'impose ici, car c'est un seul et même chemin.
- Les portées de la clé, ainsi que les adresses et les domaines auxquels elle est limitée.
- La vérification de l'expéditeur :
Fromest une adresse d'un domaine qui peut envoyer, et une adresse au nom de laquelle la clé peut envoyer. - Le quota d'envoi de l'espace de travail et sa liste de suppression.
- La signature et le suivi des ouvertures et des clics de l'adresse d'envoi, comme pour un envoi REST qui ne définit ni
signaturenitracking. - La voie : tant que la voie des diffusions est en pause, un message avec
X-OpenEmail-Stream: broadcastest refusé. - Les webhooks et les événements de remise, qui désignent le message par l'id de la réponse
250.
Nouvelles tentatives
Un message doté d'un Message-ID est envoyé une seule fois. Transmettre à nouveau le même Message-ID pour les mêmes destinataires renvoie l'id du premier message et n'envoie rien, si bien qu'un logiciel qui réessaie après une connexion interrompue ne peut pas l'envoyer deux fois. Le même message pour d'autres destinataires est un autre envoi. Voir Idempotence.
Réponses et limites
| Réponse | Quand |
|---|---|
| 250 2.0.0 | Le message est mis en file d'attente, et son id suit. |
| 535 5.7.8 | La connexion a échoué : une clé erronée, révoquée ou expirée, une clé sans emails:send, ou une clé API sous un autre nom d'utilisateur. |
| 452 4.5.3 | Plus de 50 destinataires dans un même message. Les logiciels de messagerie envoient d'eux-mêmes le reste dans un autre message. |
| 552 5.3.4 | Le message dépasse 25 Mo. |
| 550 5.6.0 | Le message ne peut pas être envoyé tel qu'il est écrit : pas de From, personne dans To, des pièces jointes trop nombreuses ou trop volumineuses, une voie inconnue. Le texte indique la raison. |
| 550 5.7.1 | L'envoi a été refusé : la clé ne peut pas envoyer au nom de cette adresse, le domaine ne peut pas encore envoyer, ou la voie des diffusions est en pause. |
| 452 4.7.0 | Le quota d'envoi de l'espace de travail est épuisé. |
| 451 4.7.1 | Plus de 300 messages d'une même clé en une minute. Les logiciels de messagerie attendent et réessaient. |
| 451 4.3.0 | Une erreur de notre côté. Réessayez sous peu. |
Une connexion qui n'a rien à envoyer se ferme au bout de cinq minutes. Une même connexion peut acheminer n'importe quel nombre de messages, l'un après l'autre.
Dans le journal des requêtes
Chaque message qu'une clé transmet est une ligne dans son journal des requêtes, avec la méthode SMTP, le chemin /emails et le statut qu'aurait eu un envoi REST : 202 quand il a été mis en file d'attente, et 403, 422 ou 429 avec le même code d'erreur quand il a été refusé. GET /keys/{id}/requests?path=/emails les liste à côté des envois REST. Une connexion qui échoue avec une vraie clé apparaît dans l'activité de cette clé.