API Document

Overview

nordicsender Engine provides a HTTP submission API.

The information is provided to the API as a POST or PUT request of JSON content. (The header of content-type: application/json must be provided.)

The API provides a response of JSON content with a content type of application/json.

Authentication is performed by providing a username/password for an Email User in the JSON document.

The API is provided at https://spsrvr.com/api/v1/send.json on your nordicsender server’s HTTP service.

Example

Example JSON document:

{
        "username":"smtpprov-u00100123",
        "password":"YOUR_SPECIFIED_PASSWORD",
        "message":{
                "html":"html content goes <b>here</b>",
                "text":"text content goes here",
                "subject":"this is the subject",
                "to":[
                        {
                                "email":"recipient@example.com",
                                "name":"John Doe"
                        }
                ],
                "from_email":"from@example.com",
                "from_name":"Your Company",
		"mailclass":"u00100123"
        }
}

Example JSON reply for success:

{"success":1,"message_id":"mid-990f39eb71e52cc5050b7b36ada937d4@example.com"}

Example JSON reply for failure:

{"success":0,"error":"no data in POST or PUT payload"}

or:

{"success":0,"error":"incorrect username/password"}

Submitting this request with curl:

cat <<'EOT' > post_body.txt
{
        "username":"smtpprov-u00100123",
        "password":"YOUR_SPECIFIED_PASSWORD",
        "message":{
                "html":"html content goes <b>here</b>",
                "text":"text content goes here",
                "subject":"this is the subject",
                "to":[
                        {
                                "email":"recipient@example.com",
                                "name":"John Doe"
                        }
                ],
                "from_email":"from@example.com",
                "from_name":"Your Company",
                "mailclass":"u00100123",
                "headers":{
                        "X-foo":"bar"
                }
        }
}
EOT

curl -X POST -H "Content-Type: application/json" --data-binary @post_body.txt http://spsrvr.com/api/v1/send.json

Submitting this request with PHP:


$mailclass='u00100123';
$password='YOUR_PASSWORD';
$json='{
        "username":"smtpprov-'.$mailclass.'",
        "password":"'.$password.'",
        "message":{
                "html":"html content goes <b>here</b>",
                "text":"text content goes here",
                "subject":"this is the subject",
                "to":[
                        {
                                "email":"recipient@example.com",
                                "name":"John Doe"
                        }
                ],
                "from_email":"from@example.com",
                "from_name":"Your Company",
                "mailclass":"'.$mailclass.'"
               }
        }';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://spsrvr.com/api/v1/send.json");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json'
));       
$output = curl_exec($ch);
var_dump($output) ;

Submitting multiple recipient request with PHP:


$mailclass='u00100123';
$password='YOUR_PASSWORD';
$json='{
        "username":"smtpprov-'.$mailclass.'",
        "password":"'.$password.'",
        "messages":[{
                "html":"html content goes <b>here</b>",
                "text":"text content goes here",
                "subject":"this is the subject",
                "to":[
                        {
                                "email":"recipient@example.com",
                                "name":"John Doe"
                        }
                ],
                "from_email":"from@example.com",
                "from_name":"Your Company",
                "mailclass":"'.$mailclass.'"
               },
               {
                "html":"html content goes <b>here</b>",
                "text":"text content goes here",
                "subject":"this is the subject",
                "to":[
                        {
                                "email":"recipient@example.com",
                                "name":"John Doe"
                        }
                ],
                "from_email":"from@example.com",
                "from_name":"Your Company",
                "mailclass":"'.$mailclass.'"
               }
            ]
        }';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://spsrvr.com/api/v1/send.json");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                                                          
    'Content-Type: application/json'
));       
$output = curl_exec($ch);
var_dump($output) ;

The API can also be accessed through SSL:

(Remove the --insecure option if you have a valid SSL certificate.)

curl -X POST -H "Content-Type: application/json" --data-binary @post_body.txt --insecure https://spsrvr.com/api/v1/send.json

Request document

  • username – email address of an email user (NOT the username of nordicsender web-interface login)
  • password – password of above user
  • message – Object containing the following fields:
Name Data type Description
html string HTML of content for email message (either the html or text key is required)
text string Text of content for email message (either the html or text key is required)
subject string Subject line of email (required)
to array List of recipients of email. Each entry in the list is an object. In that object a value for email is required and name is optional.
from_email string Email address to use in From header (required)
from_name string Name to use in From header (optional)
mailclass string Name of nordicsender MailClass (same effect as specifying an X-nordicsender-MailClass header). If not specified the default mail class will be used. (optional)
headers object Additional headers to add to the email. The key is the header name and the value is the value of the header. (optional)