SMTP web API

L’API di turboSMTP è un ottimo modo per personalizzare il nostro servizio, integrandolo dove si preferisce.

In generale, una API (Application Programming Interface) è un protocollo che definisce un’interfaccia per componenti software, in modo che possano comunicare tra di loro.

Al momento abbiamo a disposizione un metodo Send che permette di creare uno script con cui eseguire turboSMTP e inviare e-ail transazionali (conferme di login, messaggi di benvenuto, ricevute ecc.) via web, senza utilizzare il protocollo SMTP.

Quindi, se avete un sito web o un’app e volete inviare un messaggio direttamente da lì, è possibile implementare questo metodo nel vostro script e gestire facilmente l’operazione.

Qui di seguito troverete la documentazione completa. Attualmente stiamo sviluppando nuovi metodi: vi terremo aggiornati!

Scarica il codice di esempio

PHP C# Java Python Perl Ruby

 

Send (Beta 1.0)

Questo servizio vi permette di inviare un’email.

Indice

  • Parametri
  • POST request
  • MIME body message
  • Esempio di invio email (curl)
  • Esempio di invio email (PHP)
  • TurboApiClient (PHP)
  • Scarica il codice sorgente d’esempio (PHP)

 

Parametri [top]

Parametro Obbligatorio Vincolo Descrizione
to Sì Indirizzo email valido. Elenco dei destinatari. In caso di più destinatari, gli indirizzi devono essere separati da una virgola.
subject No Max 700 caratteri. L’oggetto dell’email da inviare.
from Sì Indirizzo email valido. L’indirizzo del mittente.
bcc No Indirizzo email valido. Lista copia nascosta. In caso di più destinatari, gli indirizzi devono essere separati da una virgola.
cc No Indirizzo email valido. Lista di copia. In caso di più destinatari, gli indirizzi devono essere separati da una virgola.
content No   Contenuto testuale dell’email.
tml_content No   Contenuto HMTL dell’email.
custom_headers No Formato JSON valido. Valori delle chiavi di header personalizzate da mettere nell’email. Example:

 {"X-key1":"value1", "X-key2":"value2"}
mime_raw No Formato standard MIME. Messaggio MIME, che rimpiazza content e html_content.

 

Post request [top]

Url

https://api.turbo-smtp.com/api/mail/send

L’autenticazione dell’utente avviene attraverso i seguenti parametri:

  • authuser: Nome utente
  • authpass: Password

I dati di autenticazione possono essere gestiti come parametri GET e POST parameters, o come header di richiesta https.

Esempio di 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"}

Risposta Post

Le risposte del server sono nel formato JSON. I membri dell’oggetto sono:

  • message: la risposta è “OK” in caso di successo, “error” in caso di errore
  • errors: (solo in caso di errore) una matrice che contiene i messaggi di errore

 

Risposta di successo

 { "message":"OK" }

Risposta di errore

 { "message": "error","errors": ["error message",...]}

Esempio di una risposta di errore

 { "message": "error","errors": ["'broken@@@Address.@@' recipient email not valid" , "'broken2@@@Address2.@@222' bcc email not valid"]}

 

MIME type body message [top]

Nel caso in cui si desidera inviare un’email con il body message di tipo MIME, è necessario inviarla come un parametro POST denominato “mime”.

In questo caso i parametri content e content_html vengono ignorati. Il messaggio deve essere standard, e se lo inviate senza header è necessario in ogni caso, come richiesto dalla specifica, di lasciare una riga vuota prima del body.

Questo parametro permette di inviare un file all’interno del messaggio.

 

Esempio di (curl) email sending [top]

Codice esempio per inviare un’email usando il comando curl.

Spedizione dell’email

Inviamo un’email usando la chiave di autenticazione ottenuta dalla chiamata precedente.

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

 

Esempio di (PHP) email sending [top]

Un codice PHP esemplificativo per inviare un’email con la nostra API.

Codice sorgente
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 semplice client utile per connettersi alla nostra API.

source code
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";
		}
	}
};

 

Scarica l’intero codice sorgente [top]

PHP C# Java Python Perl Ruby