L’API de turboSMTP est un excellent moyen de personnaliser notre service, en l’integrant où vous préférez.
En général, une API (Application Programming Interface) est un protocole qui définit une interface pour les composants d’un logiciel, afin qu’ils puissent communiquer les uns avec les autres.
Pour le moment nous fournissons une méthode Send qui vous permet de créer un script pour exécuter turboSMTP et envoyer des emails transactionnels (messages de confirmation, messages d’accueil, etc.) à travers du web, sans l’aide du protocole SMTP.
Donc, si vous avez un site ou une application et vous devez envoyer un message directement à partir de là, vous pouvez implémenter cette méthode dans votre script et de la gérer facilement.
Ci-dessous vous trouverez la documentation complète (en anglais). Nous sommes en train de développer des nouvelles méthodes: nous vous tiendrons au courant!
Téléchargez le code source d’exemple
Send (Beta 1.0)
Ce service vous permet d’envoyer un email.
Index
- Paramètres
- POST request
- MIME body message
- Exemple d’envoi email (curl)
- Exemple d’envoi email (PHP)
- TurboApiClient (PHP)
- Télécharger le code d’exemple (PHP)
Parametères [top]
Paramètre | Requis | Obligations | Description |
---|---|---|---|
to | Oui | Adresse email valide. | Liste des destinataires. En cas de destinataires multiples, les adresses doivent être séparées par une virgule. |
subject | Non | Max 700 characters string. | Le sujet de l’email à envoyer. |
from | Oui | Adresse email valide. | L’adresse expéditeur de l’email à envoyer. |
bcc | Non | Adresses email valide. | Liste de copie carbone invisible. En cas de destinataires multiples, les adresses doivent être séparées par une virgule. |
cc | Non | Adresses email valide. | Liste de copie carbone. En cas de destinataires multiples, les adresses doivent être séparées par une virgule. |
content | Non | Contenu textuel de l’email. | |
html_content | Non | Contenu HTML de l’email. | |
custom_headers | Non | Format JSON valide. | Valeur de la remise des clés des header personnalisés à mettre dans le courriel. Exemple:
{"X-key1":"value1", "X-key2":"value2"} |
mime_raw | Non | Format MIME standard. | Message MIME, qui remplace content and html_content. |
Post request [top]
Url
https://api.turbo-smtp.com/api/mail/send
L’authentification de l’utilisateur s’effectue avec les paramètres suivants:
- authuser: Nom de l’utilisateur
- authpass: Mot de passe
Les données d’authentification peuvent etre gerées comme paramètres GET et POST, ou comme header de https request’s.
Exemple de Post request
from:from_address@domain.com to:to1_address@domain.com,to2_address@domain.com cc:cc1_address@domain.com,cc2_address@domain.com bcc:bcc1_address@domain.com,bcc2_address@domain.com subject:subject of email content:text content of email html_content: html content of email custom_headers:{"X-key1":"value1", "X-key2":"value2"}
Réponses
Les réponses du serveur sont en format JSON. Les membres de l’objet sont:
- message: « OK » en cas de success, « error » en cas d’erreur
- errors: (seulement en cas d’erreur) tableau contenant les messages d’erreur
Réponse de success
{ "message":"OK" }
Réponse d’erreur
{ "message": "error","errors": ["error message",...]}
Exemple d’une réponse d’erreur
{ "message": "error","errors": ["'broken@@@Address.@@' recipient email not valid" , "'broken2@@@Address2.@@222' bcc email not valid"]}
MIME type body message [top]
Dans le cas où vous voulez envoyer que le corps de l’e-mail, un message de type MIME, vous devez l’envoyer comme un paramètre POST nommé « mime ».
Dans ce cas, les paramètres de contenu et content_html sont ignorés. Le message doit être standard. Si vous envoyez un message sans tête dont vous avez besoin en tout cas, tel que requis par la spécification, de laisser une ligne vide avant le corps.
Ce paramètre permet d’envoyer un fichier à l’intérieur du message.
Exemple d’envoi email (curl) [top]
Exemple de code pour envoyer un email en utilisant le commande curl.
Envoi de l’email
Envoyons un email en utilisant la clé d’authentification obtenue de l’appel précedent.
curl --Header "authuser:_username" --Header "authpass:_password" --data "to=john.smith@domain.com&subject=email subject string&from=john.smith@domain.com&bcc=mark.davies@domain.com&cc=mary.davies@domain.com&content=content email&html_content=html content of email" https://api.turbo-smtp.com/api/mail/send
Exemple d’envoi email (PHP) [top]
Un code PHP d’exemple pour envoyer un email avec notre API.
Code source
require_once "TurboApiClient.php"; // creation of the email to be sent $email = new Email(); $email->setFrom("john.smith@domain.com"); $email->setToList("mark.davies@domain.com, bruce.campbell@domain.com"); $email->setCcList("mary.davies@domain.com, mary.smith@domain.com"); $email->setBccList("maria.campbell@domain.com, don.smith@domain.com"); $email->setSubject("subject"); $email->setContent("content"); $email->setHtmlContent("html content"); $email->addCustomHeader('X-FirstHeader', "value"); $email->addCustomHeader('X-SecondHeader', "value"); $email->addCustomHeader('X-Header-to-be-removed', 'value'); $email->removeCustomHeader('X-Header-to-be-removed); // creation of a client that connects with turbo-smtp APIs $turboApiClient = new TurboApiClient("_username", "_password"); // email sending $response = $turboApiClient->sendEmail($email); // display of the operation's outcome var_dump($response);
TurboApiClient (PHP) [top]
Un simple client util à se connecter avec notre API.
Code source
require_once "TurboClient.php"; require_once "Email.php"; class TurboApiClient{ protected $username; protected $password; private $serverUrl = "https://api.turbo-smtp.com/api"; public function __construct($username, $password) { $this->username = $username; $this->password = $password; } protected function authorize(){ try { $api = new TurboClient($this->serverUrl, $this->username, $this->password); return $api; } catch (Pest_Forbidden $ex) { return null; } } public function sendEmail($email){ $api = $this->authorize(); if($api){ try { $response = $api->post( '/mail/send', $email->getPostParameters() ); return $response; } catch (Pest_NotFound $e) { return $e; } }else{ return "Authorization error"; } } };
Télécharger le code source d’exemple [top]