Notifications Email

Aperçu

Prise en charge des images: Non
Prise en charge des pièces jointes: Oui
Limites de caractères des messages:
- Corps: 32768
Créer votre URL Apprise

Syntaxe

La syntaxe valide est la suivante :

mailto://{user}:{password}@{domain}
mailto://{user}:{password}@{domain}:{port}
mailto://{domain}?user={user}&pass={password}
mailto://{user}:{password}@{domain}/{to_email}
mailto://{user}:{password}@{domain}/{to_email1}/{to_email2}/{to_emailN}

Ajouter un s au schéma, c’est-à-dire mailtos://, bascule vers une connexion STARTTLS sécurisée, avec le port 587 par défaut :

mailtos://{user}:{password}@{domain}
mailtos://{user}:{password}@{domain}:{port}
mailtos://{domain}?user={user}&pass={password}
mailtos://{user}:{password}@{domain}/{to_email}
mailtos://{user}:{password}@{domain}/{to_email1}/{to_email2}/{to_emailN}

Prise en Charge Intégrée des Fournisseurs

Apprise détecte automatiquement de nombreux fournisseurs e-mail à partir de l’adresse From déduite de votre URL. Lorsqu’un fournisseur est reconnu, Apprise configure automatiquement :

l’hôte SMTP ;
le port ;
le mode sécurisé (SSL ou STARTTLS) ;
le format d’identification (adresse e-mail complète ou identifiant).

Dans la plupart des cas, il vous suffit de fournir votre adresse e-mail et votre mot de passe.

Fournisseur	Exemple d’URL	Remarques
Google (Gmail)	`mailto://user:app-password@gmail.com`	Si la validation en 2 étapes est activée, générez un mot de passe d’application : https://security.google.com/settings/security/apppasswords
Yahoo	`mailto://user:app-password@yahoo.com`	Nécessite un mot de passe d’application : https://help.yahoo.com/kb/SLN15241.html
Fastmail	`mailto://user:app-password@fastmail.com`	Le mot de passe d’application doit autoriser SMTP. Voir les domaines pris en charge ici.
GMX	`mailto://user:password@gmx.net`	Prend aussi en charge `gmx.com`, `gmx.de`, `gmx.at`, `gmx.ch`, `gmx.fr`.
Zoho	`mailto://user:password@zoho.com`	Les valeurs par défaut du fournisseur sont appliquées automatiquement.
Yandex	`mailto://user:password@yandex.com`	La connexion peut reposer sur l’identifiant utilisateur selon les règles du domaine.
SendGrid (SMTP)	`mailto://apikey:password@sendgrid.com?from=noreply@yourdomain.com`	`from=` doit utiliser une identité d’expéditeur validée.
QQ / Foxmail	`mailto://user:password@qq.com`	Les valeurs par défaut du fournisseur sont appliquées automatiquement.
163.com	`mailto://user:password@163.com`	Les valeurs par défaut du fournisseur sont appliquées automatiquement.
Microsoft (Outlook, Hotmail, Office 365)	Utilisez `azure://` à la place	Microsoft a désactivé l’authentification SMTP basique. Utilisez le plugin `azure://`.

Cette liste n’est pas exhaustive. Des domaines supplémentaires sont détectés automatiquement lorsqu’ils sont pris en charge.

Format des Adresses E-mail

Les adresses e-mail peuvent être écrites comme suit :

user@example.com
Optional Name<user@example.com>

Cette syntaxe fonctionne dans :

les cibles de l’URL ;
from= ;
cc= ;
bcc= ;
reply=.

Si vous avez besoin d’espaces dans une URL, encodez-les en %20.

Exemple :

from=Optional%20Name<noreply@example.com>

Comportement des Destinataires

Ce que vous précisez	Ce qui se passe
Aucun destinataire et aucun `to=`	Apprise envoie l’e-mail à l’adresse expéditeur (adresse From déduite).
Cibles dans le chemin URL	Chaque cible devient un destinataire.
`to=` dans la query string	Traité comme un destinataire supplémentaire.
`cc=` / `bcc=`	Appliqué à chaque e-mail généré.
`reply=`	Définit l’en-tête Reply-To, potentiellement avec plusieurs adresses.

Utiliser des Serveurs SMTP Personnalisés

Si votre fournisseur n’est pas détecté automatiquement, configurez SMTP manuellement.

Valeurs par défaut :

mailto:// : port 25
mailtos:// : port 587 avec STARTTLS

La plupart des fournisseurs publics exigent TLS. Préférez mailtos:// pour les serveurs externes.

Exemples SMTP Authentifié

Envoyer via un hôte SMTP personnalisé :

mailtos://user:password@server.com?smtp=smtp.server.com&from=noreply@server.com

Inclure un nom d’affichage pour l’expéditeur :

mailtos://user:password@server.com?smtp=smtp.server.com&from=Optional%20Name<noreply@server.com>

Forcer SSL, généralement sur le port 465 :

mailtos://user:password@server.com:465?smtp=smtp.server.com&mode=ssl&from=noreply@server.com

Relais Local sans Authentification

Si vous utilisez Postfix, Exim ou un autre relais interne qui ne requiert pas d’authentification, omettez user et pass.

mailto://localhost?from=john@example.ca

Hôte de relais interne :

mailto://relay-server?from=noreply@example.com&to=alerts@example.com

Si l’hôte SMTP diffère de l’hôte indiqué dans l’URL :

mailto://server.com?smtp=smtp.server.com&from=noreply@server.com

Nom d’Expéditeur vs Adresse d’Expéditeur

Si vous souhaitez définir un nom d’affichage, vous pouvez utiliser :

from=Optional%20Name<noreply@example.com> (recommandé)
name=Optional%20Name&from=noreply@example.com

Si les deux sont fournis, le nom intégré à from= est prioritaire.

Manipulation des En-têtes

Email prend en charge l’injection d’en-têtes personnalisés en préfixant les clés de requête avec le symbole plus (+).

Cela est utile pour les filtres de messagerie, le routage interne et le marquage.

Un En-tête

Définissez :

X-Token: abcdefg

apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
  "mailto://localhost?to=john@example.ca&+X-Token=abcdefg"

Plusieurs En-têtes

Si vous devez contrôler certains des en-têtes envoyés au serveur de messagerie, vous pouvez générer des arguments mot-clé préfixés avec le symbole plus (+).

Par exemple, si vous souhaitez aussi transmettre les en-têtes e-mail suivants dans le payload :

X-Token: abcdefg
X-Apprise: is great

Vous structurerez alors votre e-mail comme ceci :

apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
  "mailto://localhost?to=john@example.ca&+X-Token=abcdefg&+X-Apprise=is%20great"

Remarques

Les valeurs des en-têtes doivent être encodées dans l’URL lorsqu’elles contiennent des espaces.
Apprise renseigne automatiquement X-Application et fusionne tous les en-têtes que vous définissez.

Plusieurs Destinataires

Par défaut, mailto://user:pass@domain envoie à user@domain, sauf si to= est précisé.

Envoyer à plusieurs destinataires via la forme query ou la forme chemin :

mailto://user:pass@domain/?to=target@example.com,target2@example.com
mailto://user:pass@domain/target@example.com/target2@example.com
mailto://user:pass@domain/Accounting<accounting@example.com>/Billing<billing@example.com>

Il n’existe pas de limite codifiée en dur au nombre de destinataires, même si votre serveur SMTP peut en imposer une.

cc= et bcc= s’appliquent à chaque e-mail envoyé. Si vous notifiez 3 destinataires, les mêmes listes cc et bcc sont utilisées pour chaque e-mail généré.

Pièces Jointes

Les pièces jointes sont entièrement prises en charge.

Les limites de votre fournisseur SMTP peuvent s’appliquer. Apprise n’impose pas lui-même de restriction de taille sur les pièces jointes.

Détail des Paramètres

Variable	Requis	Description
user	Oui*	Nom d’utilisateur SMTP. Peut être un identifiant ou une adresse e-mail complète. Peut aussi être précisé avec `?user=`.
pass	Oui*	Mot de passe SMTP. Peut aussi être précisé avec `?pass=`.
domain	Oui	Partie domaine de l’hôte URL. Pour `mailto://user:pass@example.com`, le domaine est `example.com`.
port	Non	Port SMTP. Par défaut : 25 (`mailto`) et 587 (`mailtos`) sauf si des valeurs fournisseur s’appliquent.
smtp	Non	Surcharge l’hôte SMTP. Si défini, la détection fournisseur est contournée.
from	Non	Adresse expéditeur. Prend en charge `Optional Name<email@example.com>`. Correspond à l’en-tête From.
name	Non	Alias historique pour le nom d’expéditeur. Si `from=` et `name=` sont fournis, `from=` est prioritaire.
to	Non	Surcharge du destinataire. Pris en charge aussi via les cibles dans le chemin URL.
cc	Non	Destinataires en copie. Séparés par des virgules. Le formatage des noms est pris en charge.
bcc	Non	Destinataires en copie cachée. Séparés par des virgules. Le formatage des noms est pris en charge.
reply	Non	Destinataires Reply-To. Séparés par des virgules. Le formatage des noms est pris en charge.
mode	Non	Mode sécurisé : `ssl` ou `starttls`. Avec `mailto://`, préciser `mode=` force une connexion sécurisée.
pgp	Non	Active le chiffrement PGP (`yes` ou `no`). La valeur par défaut est `no`.
pgpkey	Non	Chemin vers une clé publique PGP (clé d’entrée : `pgpkey`). Considéré comme sensible.
+Header	Non	Ajoute des en-têtes e-mail personnalisés en préfixant les clés avec `+`. Exemple : `?+X-Team=Ops`.

* Non requis pour les relais anonymes.

Pour éviter toute ambiguïté, tout paramètre d’URL (?key=value) surcharge les valeurs définies dans l’URL principale :

mailto://usera:pass123@domain.com?user=foobar : l’utilisateur foobar surcharge l’utilisateur usera défini dans l’URL. En revanche, comme le mot de passe n’est pas surchargé, pass123 reste utilisé.

Paramètres Globaux

Variable	Description
overflow	Ce paramètre peut être défini sur `split`, `truncate` ou `upstream`. Il détermine la manière dont Apprise remet le message que vous lui transmettez. Par défaut, il vaut `upstream`. 👉 `upstream` : ne fait aucune modification et transmet le message exactement tel qu’il a été reçu au service. 👉 `truncate` : veille à ce que le message tienne dans la limite amont documentée par le service. Si plus d’informations sont fournies que la limite définie, l’excédent est tronqué. 👉 `split` : similaire à `truncate`, sauf que si le message dépasse la limite amont documentée par le service, il est découpé en plusieurs morceaux plus petits puis envoyés séquentiellement.
format	Ce paramètre peut être défini sur `text`, `html` ou `markdown`. Certains services prennent en charge plusieurs formats de publication du contenu. La valeur par défaut varie selon le service choisi et peut correspondre à l’un de ces trois formats. Vous pouvez facultativement forcer cette option pour vous écarter du comportement par défaut. Si le service ne prend pas en charge plusieurs formats de transmission, ce champ est ignoré.
verify	Les requêtes externes vers des emplacements sécurisés, par exemple via `https`, utilisent des certificats. Par défaut, Apprise vérifie la validité de ces certificats ; si ce n’est pas le cas, aucune notification n’est envoyée à la source. Dans certains cas, un utilisateur ne dispose pas d’une autorité de certification pour valider la clé ou fait simplement confiance à la source ; dans ce cas, vous pouvez définir ce drapeau sur `no`. Par défaut, il vaut `yes`.
cto	Signifie Socket Connect Timeout. Il s’agit du nombre de secondes pendant lesquelles Requests attend que votre client établisse une connexion avec une machine distante, ce qui correspond à l’appel connect() sur la socket. La valeur par défaut est de `4.0` secondes.
rto	Signifie Socket Read Timeout. Il s’agit du nombre de secondes pendant lesquelles le client attend que le serveur envoie une réponse. La valeur par défaut est de `4.0` secondes.
emojis	Active la prise en charge des emojis, par exemple `:+1:` qui sera traduit en 👍. Par défaut, cette option vaut `no`. Remarque : selon la configuration côté serveur, l’administrateur peut désactiver globalement la prise en charge des emojis ; mais par défaut, ce n’est pas le cas.
tz	Identifie le fuseau horaire de la base IANA que vous souhaitez utiliser. Par défaut, celui-ci est détecté à partir de la configuration du serveur qui exécute Apprise. Vous pouvez le définir sur des valeurs comme `America/Toronto`, ou sur tout autre fuseau correctement formaté correspondant à votre région.

Exemples

Exemple avec un fournisseur intégré :

apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
    mailto:///example:mypassword@gmail.com

Envoyer un e-mail via un fournisseur personnalisé ; comme aucun smtp= n’est précisé, l’hôte example.com est aussi supposé être le serveur SMTP :

# Assuming the {domain} is example.com
# Assuming the {user} is george
# Assuming the {password} is pass123
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   mailto://george:pass123@example.com

# L'URL ci-dessus aurait aussi pu être écrite comme ceci :
#  mailto://example.com?user=george&pass=pass123

Si le serveur SMTP diffère du domaine, ce qui est généralement le cas, votre URL doit inclure l’argument ?smtp= :

# Assuming the {domain} is example.com
# Assuming the {user} is george
# Assuming the {password} is pass123
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   mailto://george:pass123@example.com?smtp=smtp.example.com

Dans certains cas, {user} est une adresse e-mail complète. Vous pouvez alors placer cette information dans les paramètres de l’URL :

# Assuming the {domain} is example.com
# Assuming the {user} is george@example.com
# Assuming the {password} is pass123
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "mailto://example.com?user=george@example.com&pass=pass123"

# Notez que l'esperluette (&), utilisée dans l'URL pour séparer
# les arguments, est aussi interprétée par le CLI comme une exécution
# en arrière-plan. Encadrez donc votre URL de guillemets.

# Envoyer un e-mail vers un serveur relais SMTP que vous hébergez :
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   mailto://localhost?from=john@example.ca

Les utilisateurs de serveurs SMTP personnalisés auront besoin d’une configuration légèrement plus complexe :

# Assuming the {smtp_server} is mail.example.com
# Assuming the {send_from} is joe@example.com
# Assuming the {login} is user1@example.com
# Assuming the {password} is pass123
# Assuming you want to use starttls (port 587)
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "mailtos://_?user=user1@example.com&pass=pass123&smtp=mail.example.com&from=joe@example.com"

# Remarques (pour l'URL ci-dessus) :
# - Comme aucun `to=` n'a été précisé, c'est l'adresse `from` qui est notifiée
# - `mailtos://` utilise starttls sur 587 par défaut ; si vous voulez utiliser
#   le port 465 (SSL), ajoutez simplement `mode=ssl` aux paramètres de l'URL.

Voici un exemple plus avancé où vous souhaitez utiliser ssl et un port personnalisé :

# Assuming the {smtp_server} is mail.example.com
# Assuming the {send_from} is joe@example.com
# Assuming the {login} is user1@example.com
# Assuming the {password} is pass123
# Assuming you want to use ssl on port 12522
# Assuming you want your email to go to bob@example.com and jane@yahoo.ca
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "mailtos://example.com:12522?user=user1@example.com&pass=pass123&smtp=mail.example.com&from=joe@example.com&to=bob@example.com,jane@yahoo.ca&mode=ssl"

Relais local :
```bash
apprise -t "Titre de Test" -b "Corps de Test" \
   mailto://localhost?to=john@example.com

Questions ou commentaires ?

Documentation

Vous avez repéré une faute de frappe ou une erreur ? Signalez-la ou proposez une correction .

Problèmes Techniques

Vous rencontrez un problème avec le code ? Ouvrez un ticket sur GitHub :