Notifications SparkPost

Aperçu

• Source: https://sparkpost.com/
• 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

Configuration du compte

Vous pouvez creer un compte gratuitement sur leur site web, mais cette formule comporte des restrictions.

Pour chaque domaine configure chez eux, vous pourrez y acceder depuis votre tableau de bord une fois connecte. Vous devrez generer une API key et lui accorder le droit transmission.

Syntaxe

La syntaxe valide est la suivante :

• sparkpost://{user}@{domain}/{apikey}/
• sparkpost://{user}@{domain}/{apikey}/{email}/
• sparkpost://{user}@{domain}/{apikey}/{email1}/{email2}/{emailN}/

Vous pouvez aussi preciser votre region si vous n’utilisez pas les serveurs americains :

• sparkpost://{user}@{domain}/{apikey}/?region=eu

Vous pouvez egalement ajuster le nom associe a l’adresse e-mail From :

• sparkpost://{user}@{domain}/{apikey}/?name=Darth%20Vader

Extensions d’Adresse E-mail

Si vous souhaitez utiliser des extensions d’adresse, vous devez echapper le caractere plus + avec %2B comme ceci :
sparkpost://{user}@{domain}/{apikey}/chris%2Bextension@example.com

Les champs Carbon Copy, cc=, et Blind Carbon Copy, bcc=, sont en revanche appliques a chaque e-mail envoye. Ainsi, si vous envoyez un message a 3 destinataires, les listes cc et bcc seront incluses dans chacun des 3 e-mails.

Détail des Paramètres

Variable	Obligatoire	Description
apikey	Oui	Cle API associee au domaine depuis lequel vous souhaitez envoyer vos e-mails. Elle est disponible apres connexion a leur site et acces au tableau de bord.
domain	Oui	Domaine depuis lequel vous souhaitez envoyer vos e-mails. Ce domaine doit etre enregistre et configure avec votre compte SparkPost.
user	Oui	L’utilisateur est combine au domaine indique dans l’URL pour former l’adresse From visible par vos destinataires.
batch	Non	Si le mode batch est defini sur yes, toutes les adresses e-mail sont envoyees dans un seul lot que SparkPost traitera.
email	Non	Vous pouvez specifier autant d’adresses e-mail que vous le souhaitez. Chaque adresse indiquee representera le champ To. Remarque : selon la configuration de votre compte, SparkPost peut restreindre l’envoi vers certaines adresses.
region	Non	Identifie la region du serveur a utiliser. Les options prises en charge sont eu et us. Par defaut, la valeur us est utilisee si rien n’est precise. Cela affecte le serveur API contacte pour l’envoi des e-mails.
from	Non	Permet de definir le nom associe a l’adresse e-mail From lors de l’envoi.
to	Non	Alias de la variable email. Vous pouvez y chaîner autant d’adresses To que souhaite, separees par des virgules et/ou des espaces.
cc	Non	Adresse(s) e-mail en Carbon Copy. Plusieurs valeurs peuvent etre separees par des espaces et/ou des virgules.
bcc	Non	Adresse(s) e-mail en Blind Carbon Copy. Plusieurs valeurs peuvent etre separees par des espaces et/ou des virgules.

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

Envoyer une notification SparkPost a l’adresse e-mail bill.gates@microsoft.com :

# Supposons que le {domain} configure dans notre compte SparkPost soit example.com
# Supposons que notre {apikey} soit 4b4f2918fddk5f8f91f
# Supposons que notre {email} de destination soit bill.gates@microsoft.com
# Supposons que nous voulions envoyer depuis noreply@example.com
apprise sparkpost:///noreply@example.com/4b4f2918fddk5f8f91f/bill.gates@microsoft.com

Manipulation des en-tetes

Certains utilisateurs peuvent avoir besoin d’en-tetes HTTP speciaux lors de l’envoi de leurs donnees. Pour cela, il suffit d’ajouter un symbole plus, +, devant n’importe quel parametre precise dans votre URL. Les exemples ci-dessous envoient une notification SparkPost a l’adresse bill.gates@microsoft.com en exploitant cette personnalisation des en-tetes.

# L'exemple ci-dessous definirait l'en-tete :
#    X-Token: abcdefg
#
# Supposons que le {domain} configure dans notre compte SparkPost soit example.com
# Supposons que notre {apikey} soit 4b4f2918fddk5f8f91f
# Supposons que notre {email} de destination soit bill.gates@microsoft.com
# Supposons que nous voulions envoyer depuis noreply@example.com
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "sparkpost:///noreply@example.com/4b4f2918fddk5f8f91f/bill.gates@microsoft.com/?+X-Token=abcdefg"

# Pour plusieurs en-tetes, il suffit d'ajouter d'autres entrees :
# L'exemple ci-dessous definirait les en-tetes :
#    X-Token: abcdefg
#    X-Apprise: is great
#
# Supposons que le {domain} configure dans notre compte SparkPost soit example.com
# Supposons que notre {apikey} soit 4b4f2918fddk5f8f91f
# Supposons que notre {email} de destination soit bill.gates@microsoft.com
# Supposons que nous voulions envoyer depuis noreply@example.com
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "sparkpost:///noreply@example.com/4b4f2918fddk5f8f91f/bill.gates@microsoft.com/?+X-Token=abcdefg&+X-Apprise=is%20great"

Substitution Globale

SparkPost permet d’utiliser des {{tokens}} encadres par deux accolades. Consultez leur documentation sur le templating pour plus de details. Si vous souhaitez transmettre un mot-cle et sa valeur de substitution, il suffit d’ajouter un deux-points, :, devant n’importe quel parametre precise dans votre URL. L’exemple ci-dessous envoie une notification SparkPost a bill.gates@microsoft.com en utilisant ce mecanisme.

# L'exemple ci-dessous definirait le token {{software}} pour qu'il soit remplace par Microsoft :
# Supposons que le {domain} configure dans notre compte SparkPost soit example.com
# Supposons que notre {apikey} soit 4b4f2918fddk5f8f91f
# Supposons que notre {email} de destination soit bill.gates@microsoft.com
# Supposons que nous voulions envoyer depuis noreply@example.com
apprise -vv -t "Titre du Message de Test" -b "Bill Gates works at {{software}}" \
   "sparkpost:///noreply@example.com/4b4f2918fddk5f8f91f/bill.gates@microsoft.com/?:software=Microsoft"

Vous pouvez specifier autant de tokens que vous le souhaitez. Apprise fournit egalement automatiquement quelques tokens par defaut si vous souhaitez les utiliser :

• app_id : identifiant de l’application ; il vaut generalement Apprise, mais les developpeurs d’applications personnalisees peuvent le surcharger et y placer leur propre nom.
• app_desc : description de l’application ; c’est en general une variante un peu plus explicite de app_id. Cette valeur est habituellement Apprise Notification, sauf surcharge par un developpeur.
• app_color : code hexadecimal identifiant une couleur associee au message. Par exemple, les messages info sont generalement bleus tandis que les messages warning sont orange.
• app_type : type du message lui-meme, par exemple info, warning ou success.
• app_title : titre reel, c’est-a-dire la valeur --title ou -t transmise lors de l’appel a la notification Apprise.
• app_body : corps reel du message, c’est-a-dire la valeur --body ou -b transmise lors de l’appel a la notification Apprise.
• app_url : URL associee a l’instance Apprise, trouvee dans l’objet AppriseAsset(). Sauf surcharge par un developpeur, sa valeur est https://github.com/caronc/apprise.