Argomenti in questo gruppo:
indirizzo del server, parametri obbligatori, risposte JSON
set di caratteri, content-type, parametri opzionali, risposte JSON
esempi php e curl
esempi php e curl con allegati
RealSender consente di inviare messaggi di posta elettronica tramite API (Application Programming Interface), in italiano Interfaccia di Programmazione di un’Applicazione.
In questo modo è possibile inviare la posta elettronica direttamente dalla vostra applicazione, senza passare attraverso il protocollo SMTP. Al momento sono supportate solo le richieste POST.
Indirizzo del server:
https://rsXXX-api.realsender.com/mail/send
Parametri obbligatori:
| apiuser | nome utente per l’autenticazione |
| apipass | password per l’autenticazione |
| from | indirizzo email del mittente |
| to | indirizzo email del destinatario |
| subject | oggetto della mail |
| text | corpo della mail in testo semplice |
| html | corpo della mail in formato HTML |
Se tutto è ok, il messaggio verrà inviato e riceverete una risposta JSON positiva:
{"success":true}
In caso di errori si ottiene una risposta simile a questa:
{"success":false,"errorMsgs":["Please provide the 'subject' value."]}
I contenuti devono essere trasmessi utilizzando il set di caratteri internazionale UTF-8.
Per verificarlo, aggiungere “€uro” nell’oggetto ed inviarlo. Se il set di caratteri è sbagliato, riceverete questo avviso JSON:
{"success":false,"errorMsgs":["The 'subject' value is not correctly encoded. It must be UTF-8 encoded."]}
A seconda che siano stati compilati uno solo o entrami i campi “text” e “html”, i messaggi verranno inviati utilizzando uno dei seguenti “Content-Type”:
| text | text/plain (solo testo semplice) |
| html | text/html (solo html) |
| text+html | multipart/alternative (testo ed html) le impostazioni del client di posta utilizzato decideranno quale parte visualizzare |
Parametri opzionali:
| fromname | descrizione del mittente |
| toname | descrizione del destinatario |
| replyto | indirizzo email che riceverà le risposte |
| returnpath | indirizzo email che riceverà i messaggi respinti (bounce) l’indirizzo deve essere presente tra i mittenti autorizzati di RealSender |
| cc | indirizzo email per copia conoscenza |
| ccname | descrizione dell’indirizzo email per copia conoscenza |
| bcc | indirizzo email per copia conoscenza nascosta |
| bccname | descrizione dell’indirizzo email per copia conoscenza nascosta |
| attach | file(s) da allegare - la variabile può essere presente più volte - peso max totale 3MB il contenuto del file deve trovarsi all’interno del “multipart HTTP POST” enctype=“multipart/form-data” è richiesto per variabili con INPUT TYPE=FILE |
I valori to, cc e bcc possono contenere un singolo indirizzo email oppure una lista di indirizzi email separati da virgola.
!! In RealSender il numero di destinatari per ogni singolo messaggio è limitato a 100.
Le risposte del server sono in formato JSON (JavaScript Object Notation):
| email inviata | {"success":true} |
| email NON inviata | {"success":false,"errorMsgs":["..."]} |
Richiesta POST
Metodo senza-CURL con PHP
<?php
$url = 'https://rsXXX-api.realsender.com/mail/send';
$data = array('apiuser' => 'quello che vi abbiamo inviato', 'apipass' => 'quella che vi abbiamo inviato', 'from' => 'mittente@nomedidominio.it', 'to' => 'destinatario@nomedidominio.it', 'subject' => 'oggetto del messaggio', 'text' => 'corpo della mail in testo semplice', 'html' => 'corpo della mail in formato HTML');
// utilizzare 'http' anche se si invia la richiesta a https://...
$options = array(
'http' => array(
'header' => "Content-type: application/x-www-form-urlencoded\r\n",
'method' => 'POST',
'content' => http_build_query($data),
),
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
var_dump($result);
?>Richiesta POST
Metodo CURL
curl -d 'apiuser=quello che vi abbiamo inviato&apipass=quella che vi abbiamo inviato&from=mittente@nomedidominio.it&to=destinatario@nomedidominio.it&subject=oggetto del messaggio&text=corpo della mail in testo semplice&html=corpo della mail in formato HTML' https://rsXXX-api.realsender.com/mail/sendRichiesta POST con allegati (max 5: attach1, attach2, …)
Metodo senza-CURL con PHP
<?php
require_once 'HTTP/Request2.php';
$config = array('use_brackets' => false,
);
$request = new HTTP_Request2('https://rsXXX-api.realsender.com/mail/send',
HTTP_Request2::METHOD_POST,
$config);
$data = array('apiuser' => 'quello che vi abbiamo inviato',
'apipass' => 'quella che vi abbiamo inviato',
'from' => 'mittente@nomedidominio.it',
'to' => 'destinatario@nomedidominio.it',
'subject' => 'oggetto del messaggio',
'text' => 'corpo della mail in testo semplice',
'html' => 'corpo della mail in formato HTML');
foreach ($data as $k => $d) {
$request->addPostParameter($k, $d);
};
$request->addUpload('attach1', './sample.pdf', 'sample.pdf', 'application/pdf');
$request->addUpload('attach2', './sample.txt', 'sample.txt', 'text/plain');
$result = $request->send();
var_dump($result);
?>Richiesta POST con allegati
Metodo CURL
curl -F 'apiuser=quello che vi abbiamo inviato' \
-F 'apipass=quella che vi abbiamo inviato' \
-F 'from=mittente@nomedidominio.it' \
-F 'to=destinatario@nomedidominio.it' \
-F 'subject=oggetto del messaggio' \
-F 'text=corpo della mail in testo semplice' \
-F 'html=corpo della mail in formato HTML' \
-F 'attach=@sample.pdf;type=application/pdf' \
-F 'attach=@sample.txt;type=text/plain' \
https://rsXXX-api.realsender.com/mail/send