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]

 {"X-key1":"value1", "X-key2":"value2"}

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