Sarv.com

PHP

Choose Language

Messages Calls

Info! This is Beta version, if you have any problem in using API, please mail us at support@sarv.com

/messages/sendMail

Send a new transactional message through Sarv

Example Call


<?php

$recipients = array(
    array(
        'email' => 'recipient1.email@example.com',
        'name' => 'Recipient1 Name'
    ),
    array(
        'email' => 'recipient2.email@example.com',
        'name' => 'Recipient2 Name'
    )
);
try {
    require_once 'SarvMTA_PHP/Sarv.php';
    $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
    $smtp_user_name = "smtp12345";
    foreach ($recipients as $recipient) {
        $message = array();
        $message["html"] = "Example HTML content";
        $message["text"] = "Example text content";
        $message["subject"] = "example subject";
        $message["from_email"] = "from_email@example.com";
        $message["to"] = array(
            array("email" => $recipient['email'], "name" => $recipient['name'], "type" => "to")
        );
        $message["headers"] = array("Reply-To" => "message.reply@example.com", "X-Unique-Id" => "Id");
        $message["attachments"] = array(array("type" => "text/plain", "name" => "myfile.txt", "content" => "ZXhhbXBsZSBmaWxl"));
        $message["images"] = array(array("type" => "image/png", "name" => "IMAGECID", "content" => "dgfdddger"));

        $result = $sarv->messages->sendMail($smtp_user_name, $message);
        print_r($result);
        /*
          Array
          (
          [status] => "success"
          [message] => "message have been Queued ... "
          )
         */
    }
} catch (Sarv_Error $e) {
    // Sarv errors are thrown as exceptions
    echo "A sarv error occurred: " . get_class($e) . " - " . $e->getMessage();
}
?>

Example Success Response


Array
(
    [status] => "success"
    [message] => "message have been Queued ... "
)

Example Error Response


Array
(
    [status]=> "error"
    [code]=> -1
    [name]=> "AuthenticationError"
    [message]=> "Token MissMatch"
)
Parameters
owner_id* string a valid Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES APP DOMAIN
smtp_user_name* string a valid smtp user name
message* struct the information on the message to send
html ** string the full HTML content to be sent
text ** string optional full text content to be sent
subject string the message subject
from_email string the sender email address.
email
from_name string optional from name to be used
to array an array of recipient information.
to[] struct a single recipient's information.
email* string the email address of the recipient
required
name string the optional display name to use for the recipient
type string the header type to use for the recipient, defaults to "to" if not provided
oneof(to, cc, bcc)
headers struct optional extra headers to add to the message (most headers are allowed)
X-STes-TrackOpen string yes/no Enable open tracking for the message
X-STes-TrackClick string html/text/both/no Enable click tracking for the message
X-STes-Autotext string yes/no Automatically generate a plain-text version of the email from the HTML content
X-STes-AutoHtml string yes/no Automatically generate an HTML version of the email from the plain-text content.
X-STes-TrackingDomain string Set a custom domain to use for tracking opens and clicks
X-STes-SigningDomain string Set a custom domain to use for SPF/DKIM signing (for "via" or "on behalf of" in email clients)
X-STes-ReturnPathDomain string Specify a custom domain to use for the message's return-path domain
attachments array an array of supported attachments to add to the message
attachments[] struct a single supported attachment
type string the MIME type of the attachment
name string the file name of the attachment
content string the content of the attachment as a base64-encoded string
images array an array of embedded images to add to the message
images[] struct a single embedded image
type string the MIME type of the image - must start with "image/"
name string the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
content string the content of the image as a base64-encoded string
* compulsory field
** Either 'html' field Or 'text' field compulsory
Return Value: Success
struct the results of sending mail
status string queued
message string human readable message
Return Value: Error
struct the error results when attempt to sending mail
status string error
message string human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/messages/sendTemplate

Send a new transactional message using templates

Example Call


<?php

$recipients = array(
    array(
        'email' => 'recipient1.email@example.com',
        'name' => 'Recipient1 Name'
    ),
    array(
        'email' => 'recipient2.email@example.com',
        'name' => 'Recipient2 Name'
    )
);
try {
    require_once 'SarvMTA_PHP/Sarv.php';
    $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
    $smtp_user_name = "smtp12345";
    foreach ($recipients as $recipient) {
        $message = array();
        $message["template_id"] = "template id";
        $message["subject"] = "example subject";
        $message["from_email"] = "from_email@example.com";
        $message["to"] = array(
            array("email" => $recipient['email'], "name" => $recipient['name'], "type" => "to")
        );
        $message["headers"] = array("Reply-To" => "message.reply@example.com", "X-Unique-Id" => "Id");
        $message["dynamic_value"] = array("NAME" => "xyz", "Email" => "info@example.com");
        $message["attachments"] = array(array("type" => "text/plain", "name" => "myfile.txt", "content" => "ZXhhbXBsZSBmaWxl"));
        $message["images"] = array(array("type" => "image/png", "name" => "IMAGECID", "content" => "dgfdddger"));

        $result = $sarv->messages->sendTemplate($smtp_user_name, $message);
        
        print_r($result);
        /*
          Array
          (
          [status] => "success"
          [message] => "message have been Queued ... "
          )
         */
    }
} catch (Sarv_Error $e) {
    // Sarv errors are thrown as exceptions
    echo "A sarv error occurred: " . get_class($e) . " - " . $e->getMessage();
}
?>

Example Success Response


Array
(
    [status] => "success"
    [message] => "message have been Queued ... "
)

Example Error Response


Array
(
    [status]=> "error"
    [code]=> -1
    [name]=> "AuthenticationError"
    [message]=> "Token MissMatch"
)
Parameters
owner_id* string a valid Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES APP DOMAIN
smtp_user_name* string a valid smtp user name
message* struct the information on the message to send
template_id * string previously created template id
subject string the message subject
from_email string the sender email address.
email
from_name string optional from name to be used
to array an array of recipient information.
to[] struct a single recipient's information.
email* string the email address of the recipient
required
name string the optional display name to use for the recipient
type string the header type to use for the recipient, defaults to "to" if not provided
oneof(to, cc, bcc)
headers struct optional extra headers to add to the message (most headers are allowed)
X-STes-TrackOpen string yes/no Enable open tracking for the message
X-STes-TrackClick string html/text/both/no Enable click tracking for the message
X-STes-Autotext string yes/no Automatically generate a plain-text version of the email from the HTML content
X-STes-AutoHtml string yes/no Automatically generate an HTML version of the email from the plain-text content.
X-STes-TrackingDomain string Set a custom domain to use for tracking opens and clicks
X-STes-SigningDomain string Set a custom domain to use for SPF/DKIM signing (for "via" or "on behalf of" in email clients)
X-STes-ReturnPathDomain string Specify a custom domain to use for the message's return-path domain
dynamic_value struct optional dynamic values to replace dynamic fields on template. Dynamic fields are case sensitive. Example
NAME string xyz
Email string info@example.com
attachments array an array of supported attachments to add to the message
attachments[] struct a single supported attachment
type string the MIME type of the attachment
name string the file name of the attachment
content string the content of the attachment as a base64-encoded string
images array an array of embedded images to add to the message
images[] struct a single embedded image
type string the MIME type of the image - must start with "image/"
name string the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
content string the content of the image as a base64-encoded string
* compulsory field
Return Value: Success
struct the results of sending mail
status string queued
message string human readable message
Return Value: Error
struct the error results when attempt to sending mail
status string error
message string human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.

/messages/sendTemplateHTTPGet

Send a new transactional message using templates (HTTP GET method). This method doesn't require SARV Library.

Example Call


<?php

$query = array(
    'owner_id' => 'owner_id',
    'token' => 'token',
    'smtp_user_name' => 'smtp123456',
    'template_id' => 'template_id',
    'subject' => 'hello',
    'from_email' => 'hello@example.com',
    'to' => 'info@example.com',
    'dynamic_value' => array('NAME' => 'xyz', 'Email' => 'xyz@example.com')
);
$url = "http://api.SarvTES_APP_DOMAIN/v1.0/messages/sendTemplateHTTPGet?" . http_build_query($query);
echo file_get_contents($url);

?>

Example Success Response


{
    "status" : "success",
    "message" : "250 Message Queued...";
}

Example Error Response


{
    "status": "error",
    "code": -1,
    "name": "AuthenticationError",
    "message": "Token MissMatch"
}
Parameters
owner_id* string a valid Sarv User Id
token* string a valid token
smtp_user_name* string a valid smtp user name
template_id* string a valid previously created template id
subject* string URL encoded subject
from_email* string URL encoded from email
to* string URL encoded to email
dynamic_value struct optional dynamic values to replace dynamic fields on template. Dynamic fields are case sensitive. Example
NAME URL encoded string xyz URL encoded string
Email URL encoded string info%40example.com URL encoded string
* compulsory field
Return Value: Success
struct the results of sending mail
status string queued
message string human readable message
Return Value: Error
struct the error results when attempt to sending mail
status string error
message string human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.
You can also use another PHP library to send mails like PHPMailer, Swift Mailer, CodeIgniter etc.

/messages/getMessageInfo

get list of messages of specific x-unique-id
Note:- By default first 100 record will be fetch if don't pass second argument i.e. '$skip_page' or pass value of '$skip_page' is 0, if you want to fetch next 100 record then pass value of '$skip_page' is 1, and so on.

Example Call


<?php
    try {
        require_once 'SarvMTA_PHP/Sarv.php';
        $sarv = new Sarv('owner_id', 'token', 'SarvTES_APP_DOMAIN');
        $x_unique_id = "test";
        $skip_page = 0;
        
        $result = $sarv->messages->getMessageInfo($x_unique_id, $skip_page);
        print_r($result);
        /*
        Array
        (
            [status] => "success"
            [message_data] => Array
                            (
                                [0] => Array
                                    (
                                        [subject] => this is subject ..
                                        [sender] => xyz@sarv.com
                                        [email] => abc@sarv.com
                                        [sendFrom] => 10.0.0.0
                                        [mailSize] => 1919
                                        [attchSize] => 0
                                        [status] => delivered
                                        [time] => 1458034022169
                                        [open] => 1
                                        [openData] => Array
                                            (
                                                [ip] => Array
                                                    (
                                                        [0] => 0.0.0.0
                                                        [1] => 0.0.0.0
                                                    )

                                                [ua] => Array
                                                    (
                                                        [0] => Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
                                                        [1] => Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
                                                    )

                                                [time] => Array
                                                    (
                                                        [0] => 1458039067963
                                                        [1] => 1458039067978
                                                    )

                                            )

                                        [clickData] => Array
                                            (
                                                [ip] => Array
                                                    (
                                                        [0] => 0.0.0.0
                                                        [1] => 0.0.0.0
                                                    )

                                                [ua] => Array
                                                    (
                                                        [0] => Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
                                                        [1] => Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
                                                    )

                                                [time] => Array
                                                    (
                                                        [0] => 1458039068888
                                                        [1] => 1458039069999
                                                    )

                                            )

                                        [click] => 1
                                    )
                            )
        )
        */
    } catch(Sarv_Error $e) {
        // Sarv errors are thrown as exceptions
        echo "A sarv error occurred: " . get_class($e) . " - " . $e->getMessage();
    }
?>

Example Success Response


Array
(
    [status] => "success"
    [message_data] => Array
                    (
                        [0] => Array
                            (
                                [subject] => this is subject ..
                                [sender] => xyz@sarv.com
                                [email] => abc@sarv.com
                                [sendFrom] => 10.0.0.0
                                [mailSize] => 1919
                                [attchSize] => 0
                                [status] => delivered
                                [time] => 1458034022169
                                [open] => 1
                                [openData] => Array
                                    (
                                        [ip] => Array
                                            (
                                                [0] => 0.0.0.0
                                                [1] => 0.0.0.0
                                            )

                                        [ua] => Array
                                            (
                                                [0] => Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
                                                [1] => Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
                                            )

                                        [time] => Array
                                            (
                                                [0] => 1458039067963
                                                [1] => 1458039067978
                                            )

                                    )

                                [clickData] => Array
                                    (
                                        [ip] => Array
                                            (
                                                [0] => 0.0.0.0
                                                [1] => 0.0.0.0
                                            )

                                        [ua] => Array
                                            (
                                                [0] => Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
                                                [1] => Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
                                            )

                                        [time] => Array
                                            (
                                                [0] => 1458039068888
                                                [1] => 1458039069999
                                            )

                                    )

                                [click] => 1
                            )
                    )
)

Example Error Response


Array
(
    [status]=> "error"
    [code]=> -1
    [name]=> "AuthenticationError"
    [message]=> "Token MissMatch"
)
Parameters
owner_id* string a valid Sarv User Id
token* string a valid token
SarvTES_APP_DOMAIN* string a valid SarvTES APP DOMAIN
x_unique_id* string a valid x-unique-id
skip_page integer a valid skip page
* compulsory field
Return Value: Success
struct the results of get mail info
status string queued
message string human readable message
Return Value: Error
struct the error results when attempt to get mail info
status string error
message string human readable message
type string one of the error type as bellow table
Error types
ValidationError The parameters passed to the API call are invalid or not provided when required.
GeneralError An unexpected errors occurred processing the request. Sarv Developers will be notified.
AuthenticationError Provided owner_id and token was not matched.