Sarv.com

JSON

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 Request JSON

            
{
    "owner_id": "example id",
    "token": "example token",
    "smtp_user_name":"smtp12345",
    "message": {
        "html": "Example HTML content",
        "text": "Example text content",
        "subject": "example subject",
        "from_email": "message.from_email@example.com",
        "from_name": "Example Name",
        "to": [
            {
                "email": "recipient.email@example.com",
                "name": "Recipient Name",
                "type": "to"
            }
        ],
        "headers": {
            "Reply-To": "message.reply@example.com",
            "X-Unique-Id": "id "
        },
        "attachments": [
            {
                "type": "text/plain",
                "name": "myfile.txt",
                "content": "ZXhhbXBsZSBmaWxl"
            }
        ],
        "images": [
            {
                "type": "image/png",
                "name": "IMAGECID",
                "content": "ZXhhbXBsZSBmaWxl"
            }
        ]
    }
}

Example Success Response


{
    "status" : "success",
    "message" : "message have been 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
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 List Tracking Domain
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 Request JSON

            
{
    "owner_id": "example id",
    "token": "example token",
    "smtp_user_name":"smtp12345",
    "message": {
        "template_id": "Template Id",
        "subject": "example subject",
        "from_email": "message.from_email@example.com",
        "from_name": "Example Name",
        "to": [
            {
                "email": "recipient.email@example.com",
                "name": "Recipient Name",
                "type": "to"
            }
        ],
        "headers": {
            "Reply-To": "message.reply@example.com",
            "X-Unique-Id": "id "
        },
        "dynamic_value": {
            "NAME": "xyz",
            "Email": "info@example.com"
        },
        "attachments": [
            {
                "type": "text/plain",
                "name": "myfile.txt",
                "content": "ZXhhbXBsZSBmaWxl"
            }
        ],
        "images": [
            {
                "type": "image/png",
                "name": "IMAGECID",
                "content": "ZXhhbXBsZSBmaWxl"
            }
        ]
    }
}

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
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 List Tracking Domain
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)

Note: Use this method to integrate third party applications (Like IVR webhooks). It requires less dependency. All name and values should be URL encoded. See here

Example HTTP GET request using cURL

            
curl "http://api.SarvTES_APP_DOMAIN/v1.0/messages/sendTemplateHTTPGet?owner_id=owner_id&token=token&smtp_user_name=smtp12345&template_id=template_id&subject=hello&from_email=info%40example.com&to=xyz%40example.com&dynamic_value%5BNAME%5D=xyz&dynamic_value%5BEmail%5D=xyz%40example.com"

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 List Tracking Domain
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/getMessageInfo

get list of messages of specific x-unique-id

Example Call


{
    "owner_id": "example id",
    "token": "example token",
    "x_unique_id":"test",
    "skip_page":0
}

Example Success Response


{
	"status": "success",
	"message_data": [{
		"subject": "this is subject ..",
		"sender": "xyz@sarv.com",
		"email": "abc@sarv.com",
		"sendFrom": "0.0.0.0",
		"mailSize": 1919,
		"attchSize": 0,
		"status": "delivered",
		"time": 1458034022169,
		"open": 1,
		"openData": {
			"ip": [
				"0.0.0.0", "0.0.0.0"
			],
			"ua": [
				"Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
				"Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)"
			],
			"time": [
				1458039067963, 1458039067978
			]
		},
		"clickData": {
			"ip": [
				"0.0.0.0", "0.0.0.0"
			],
			"ua": [
				"Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
				"Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)"
			],
			"time": [
				1458039068888, 1458039069999
			]
		},
		"click": 1
	}]
}

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
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.