Topics in this area:
server address, mandatory parameters, JSON answers
charset, content-type, optional parameters, JSON responses
php and curl examples
php and curl examples with attachments
RealSender lets you send email messages via API (Application Programming Interface).
In this way you can dispatch the emails directly from your application, without passing through smtp (Simple Mail Transfer Protocol). We currently support POST requests only.
Server address:
https://rsXXX-api.realsender.com/mail/send
Required/mandatory parameters:
| apiuser | authentication user name |
| apipass | authentication password |
| from | sender email address |
| to | recipient email address |
| subject | subject of the email |
| text | email body in plain text |
| html | email body in HTML format |
If everything is ok, the message will be sent and you will receive a positive JSON answer:
{"success":true}
In case of errors you will get something like this:
{"success":false,"errorMsgs":["Please provide the 'subject' value."]}
The contents must be sent using the UTF-8 international charset.
To test it, add “€uro” in your subject and submit it. If the charset is wrong, you will receive this JSON warning:
{"success":false,"errorMsgs":["The 'subject' value is not correctly encoded. It must be UTF-8 encoded."]}
Depending on whether you have filled in one or both the fields “text” and “html”, the messages will be sent using one of these “Content-Type”:
| text | text/plain (text only) |
| html | text/html (html only) |
| text+html | multipart/alternative (both text and html) email client settings will decide which part is displayed |
Not required/optional parameters:
| fromname | sender description |
| toname | recipient description |
| replyto | email address that will receive the replies |
| returnpath | email address that will receive the bounced mails it must be present among the RealSender’s authorized senders |
| cc | carbon copy email address |
| ccname | carbon copy description |
| bcc | blind carbon copy email address |
| bccname | blind carbon copy description |
| attach | file(s) to be attached - can be present multiple times in the form - 3MB max weight the file contents must be part of the multipart HTTP POST enctype=“multipart/form-data” is required for INPUT TYPE=FILE |
To, cc and bcc values can contain a single email address or a comma separated list of email addresses.
!! Within RealSender the total number of recipients for each piece of email is limited to 25 (it can be increased up to 100).
The server’s responses are in JSON (JavaScript Object Notation) format:
| email sent | {"success":true} |
| email NOT sent | {"success":false,"errorMsgs":["..."]} |
POST request
CURL-less method with PHP
<?php
$url = 'https://rsXXX-api.realsender.com/mail/send';
$data = array('apiuser' => 'the one we provided you', 'apipass' => 'the one we provided you', 'from' => 'sender@example.com', 'to' => 'recipient@example.com', 'subject' => 'subject of the message', 'text' => 'email body in plain text', 'html' => 'email body in HTML format');
// use key 'http' even if you send the request to 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);
?>POST request
CURL method
curl -d 'apiuser=the one we provided you&apipass=the one we provided you&from=sender@example.com&to=recipient@example.com&subject=subject of the message&text=email body in plain text&html=email body in HTML format'https://rsXXX-api.realsender.com/mail/sendPOST request with attachments (max 5: attach1, attach2, …)
CURL-less method with 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' => 'the one we provided you',
'apipass' => 'the one we provided you',
'from' => 'sender@example.com',
'to' => 'recipient@example.com',
'subject' => 'subject of the message',
'text' => 'email body in plain text',
'html' => 'email body in HTML format');
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);
?>POST request with attachments
CURL method
curl -F 'apiuser=the one we provided you' \
-F 'apipass=the one we provided you' \
-F 'from=sender@example.com' \
-F 'to=recipient@example.com' \
-F 'subject=subject of the message' \
-F 'text=email body in plain text' \
-F 'html=email body in HTML format' \
-F 'attach=@sample.pdf;type=application/pdf' \
-F 'attach=@sample.txt;type=text/plain' \
https://rsXXX-api.realsender.com/mail/send