Sending mail using Web API

Previously, we have provided a sample for sending mail using PHP API. This time, we're going to solve the same task using Web API of Aurora Corporate. And since the most tricky part here is uploading attachments and sending them out with a message, we'll cover that aspect as well.

In this sample, we'll use PHP to demonstrate the idea. The same can be done using any other programming language, JavaScript for example.

The first thing we're going to do is add a function which will send POST requests via cURL, and then we'll use that same function for each Web API request.

function postdata($sUrl, $aPost, $sToken="") {
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $sUrl);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,0);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,0);
    curl_setopt($curl, CURLOPT_HEADER,0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $aPost);
    if ($sToken!="") curl_setopt($curl, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$sToken));
    $result = curl_exec($curl);
    curl_close($curl);
    if ($result !== false) {
        $result=json_decode($result,true);
    }
    return $result;
} 

A very important bit here is that, with every request (except performing the authentication), we're sending out authorization token in request headers.

In order to get the token value, we're sending Core.Login request with account credentials as parameters:

$sUsername = 'username@domain.com';
$sPassword = 'myPassWord';
    
$sQuery = 'http://localhost/aurora/?/Api/';
$aLoginParams = ['Module' => 'Core', 'Method' => 'Login', 'Parameters' => 
    '{"Login": "'.$sUsername.'", "Password": "'.$sPassword.'"}'
];
    
$aLoginResult = postdata($sQuery, $aLoginParams);
    
if (isset($aLoginResult["Result"]["AuthToken"])) {
    $sToken = $aLoginResult["Result"]["AuthToken"];

In addition to authorization token, we'll need to get ID of the account, that's done by sending a separate Core.GetAuthenticatedAccount request:

$aAccountParams = ['Module' => 'Core', 'Method' => 'GetAuthenticatedAccount', 'Parameters' => '{"AuthToken": "'.$sToken.'"}'];
$aAccountResults = postdata($sQuery, $aAccountParams, $sToken);
if (isset($aAccountResults["Result"]["EntityId"])) {
    $iAccountID = intval($aAccountResults["Result"]["EntityId"]);

Prior to sending message with attachment, we need to upload it first using Mail.UploadAttachment method.

$sFilePath = 'D:/Temp/image.png';
$aUploadParams = array('Module' => 'Mail','Method' => 'UploadAttachment','Parameters' => '{"AccountID":'.$iAccountID.'}', 'UploadData' => new CURLFile($sFilePath));
$aUploadResults = postdata($sQuery, $aUploadParams, $sToken);

If you examine $aUploadResults value upon attachment upload:

...
[Result] => Array
  (
    [Attachment] => Array
      (
        [Name] => image.png
        [FileName] => image.png
        [TempName] => upload-post-a086434a3ec22b13ad5adb55d758e0f8
        [MimeType] => image/png
        [Size] => 115098
...

you'll see that additionally to actual filename, a temporary file name is returned. We'll use both of those when supplying attachment parameters for sending message out.

$aSendDetails=[
    "AccountID" => $iAccountID,
    "To" => "otheruser@somedomain.com",
    "Subject" => "Mail sent with Web API",
    "Text" => "Some message text here",
    'Attachments' => [
        $aUploadResults["Result"]["Attachment"]["TempName"] => 
            [ $aUploadResults["Result"]["Attachment"]["Name"], "", 0, 0, "" ]
    ]
];
$aSendParams = ['Module' => 'Mail', 'Method' => 'SendMessage', 'Parameters' => json_encode($aSendDetails)];
$aSendResults = postdata($sQuery, $aSendParams, $sToken);

As you can see, 'Attachments' holds an array with temporary file name as index, and a set of parameters as value, starting with actual filename. The other parameters there are only used for inline images and hold Content-ID, inline flag, linked flag and Content-Location respectively.

By default, plaintext messages are sent out. If you need to send HTML message, add the following value to $aSendDetails array:

"IsHtml" => true,

Below, please find the complete sample demonstrating the use of Web API for sending mail message with attachment out.

<?php
    
function postdata($sUrl, $aPost, $sToken="") {
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $sUrl);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,0);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,0);
    curl_setopt($curl, CURLOPT_HEADER,0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $aPost);
    if ($sToken!="") curl_setopt($curl, CURLOPT_HTTPHEADER, array('Authorization: Bearer '.$sToken));
    $result = curl_exec($curl);
    curl_close($curl);
    if ($result !== false) {
        return (json_decode($result,true));
    }
    return false;
}
    
$sUsername = 'username@domain.com';
$sPassword = 'myPassWord';
    
$sQuery = 'http://localhost/aurora/?/Api/';
$aLoginParams = ['Module' => 'Core', 'Method' => 'Login', 'Parameters' => 
    '{"Login": "'.$sUsername.'", "Password": "'.$sPassword.'"}'
];
    
$aLoginResult = postdata($sQuery, $aLoginParams);
    
if (isset($aLoginResult["Result"]["AuthToken"])) {
    $sToken = $aLoginResult["Result"]["AuthToken"];
        
    $aAccountParams = ['Module' => 'Core', 'Method' => 'GetAuthenticatedAccount', 'Parameters' => '{"AuthToken": "'.$sToken.'"}'];
    $aAccountResults = postdata($sQuery, $aAccountParams, $sToken);
    if (isset($aAccountResults["Result"]["EntityId"])) {
        $iAccountID = intval($aAccountResults["Result"]["EntityId"]);
        
        $sFilePath = 'D:/Temp/image.png';
        $aUploadParams = array('Module' => 'Mail','Method' => 'UploadAttachment','Parameters' => '{"AccountID":'.$iAccountID.'}', 'UploadData' => new CURLFILE($sFilePath));
        $aUploadResults = postdata($sQuery, $aUploadParams, $sToken);
    
        $aSendDetails=[
            "AccountID" => $iAccountID,
            "To" => "otheruser@somedomain.com",
            "Subject" => "Mail sent with Web API",
            "Text" => "Some message text here",
            'Attachments' => [
                $aUploadResults["Result"]["Attachment"]["TempName"] => 
                    [ $aUploadResults["Result"]["Attachment"]["Name"], "", 0, 0, "" ]
            ]
        ];
    
        $aSendParams = ['Module' => 'Mail', 'Method' => 'SendMessage', 'Parameters' => json_encode($aSendDetails)];
        $aSendResults = postdata($sQuery, $aSendParams, $sToken);
    }
}