The Sendinc REST API enables developers to easily interact with the Sendinc service via third-party applications. Requests are made to the API using standard GET and POST commands and the API returns its results in XML or JSON depending on the extension you provide in your request (.xml for XML, .json for JSON). Some requests may return an empty response.

Examples

For the examples in this section, we’re using the command line utility cURL. This should provide a good platform to familiarize yourself with the API before integrating it into your application using the programming language of your choice.

Authentication

The REST API utilizes HTTP basic access authentication over SSL for each request. To authenticate, simply accompany each request with your Sendinc Email Alias and Sendinc Password. If you don’t have a Sendinc account, a free one can be created here.

Getting Your Account Information

This command uses a GET request to fetch information about your account.

JSON Request:

$ curl -u email@address.com:password https://rest.sendinc.com/account.json

XML Request:

$ curl -u email@address.com:password https://rest.sendinc.com/account.xml

Sample JSON Response:

{\n  
\"account\":\n  
{\n    
\"email\": \"email@address.com\",\n    
\"first_name\": \"Bill\",\n    
\"last_name\": \"Lumbergh\",\n    
\"date_created\": \"2011-07-11 18:01:22\",\n    
\"type\": \"pro\",\n    
\"max_messages_per_day\": 200,\n    
\"max_recipients\": 100,\n    
\"max_attachment_size\": 209715200\n  
}\n
}

Sample XML Response:

<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n  
<account>\n    
<date_created>2011-07-11 18:01:22</date_created>\n    <email>email@address.com</email>\n    
<first_name>Bill</first_name>\n    
<last_name>Lumbergh</last_name>\n    <max_attachment_size>209715200</max_attachment_size>\n    <max_messages_per_day>200</max_messages_per_day>\n    <max_recipients>100</max_recipients>\n    
<type>pro</type>\n  
</account>    

Sending a Message

Sending a message involves a POST command to /message.json or /message.xml using the parameters in the following table:

Attachments

Attachments can be added to a message using a multipart/form-data formatted request. Files included in the request (e.g. Content-Disposition: file;) will be treated as attachments for the message. Attachments are represented in the example below using the @ operator to signal cURL to read the data from the file path specified after the @. Note that the parameter name of files (att_0 and att_1 in the below example) are not important as the actual name of the file (document.pdf and sourcecode.cpp) is what the server will use as the names of the file to be attached to the message.

curl -u email@address.com:password \\\n
-X POST \\\n
-F \"message=Message Body\" -F \"email=email@address.com\" \\\n
-F \"recipients=recipient@address.com,another@address.com\" \\\n
-F \"recipients_cc=carbonrecipient@address.com\" \\\n
-F \"subject=My Subject\" \\\n
-F att_0=@document.pdf -F att_1=@sourcecode.cpp \\\n
https://rest.sendinc.com/message.json"

The command will return an empty response if there were no errors encountered.

Masquerading (Corporate Accounts Only)

Administrators of Sendinc Sendinc Corporate accounts can send messages on behalf of their users by supplying the respective user’s email address in the email parameter.

Retrieving a Message

Retrieving a message involves passing the message ID (a rather long string of hex-encoded data) to the REST API via a GET request. The message ID can be found in the source of a secure message in the X-Sendinc-Message-Id header.

Sample JSON Response:

{\n  
\"message\":\n  
{\n    
\"body\":\"Did you get the memo about this?\",\n    
\"subject\":\"TPS Reports\",\n    
\"sender_name\":\"Bill Lumbergh\",\n    
\"sender_email\":\"bill@initech.com\",\n    
\"created\":1313619886,\n    
\"expires\":1316211886,\n    
\"recipient\":\"peter@initech.com\",\n    
\"recipients\":{\n      
\"to\":[\n        
\"peter@initech.com\"\n      
],\n      
\"cc\":[\n        
\"dom@initech.com\",\n        
\"bob@initech.com\"\n      
]\n    
},\n    
\"attachments\":[\n      
{\n        
\"id\":0,\n        
\"name\": \"newtpsreportcoversheetmemo.doc\",\n        \"short_name\":\"newtpsreportcovershe...o.doc\",\n        
\"icon\":\"doc.png\",\n        
\"size\":71168,\n        
\"content_type\":\"application/msword\"\n      
}\n    
]\n  
}\n
}

Sample XML Reponse:

<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n  
<message>\n    
<attachments>\n      
<element>\n        
<content_type>application/msword</content_type>\n        
<icon>doc.png</icon>\n        
<id>0</id>\n        
<name>newtpsreportcoversheetmemo.doc</name>\n        <short_name>newtpsreportcovershe...o.doc</short_name>\n        
<size>71168</size>\n      
</element>\n    
</attachments>\n    
<body>Did you get the memo about this?</body>\n    
<created>1313619886</created>\n    
<expires>1316211886</expires>\n    
<recipient>peter@initech.com</recipient>\n    
<recipients>\n      
<cc>\n        
<element>dom@initech.com</element>\n        
<element>bob@initech.com</element>\n      
</cc>\n      
<to>\n        
<element>peter@initech.com</element>\n      
</to>\n    
</recipients>\n    
<sender_email>bill@initech.com</sender_email>\n    
<sender_name>Bill Lumbergh</sender_name>\n    
<subject>TPS Reports</subject>\n  
</message>

Downloading an Attachment

Attachments can be received via a GET request containing the message ID (taken from the original secure message notification email) and the attachment ID (from the message API response). Attachments will be returned to your application using the content-type that Sendinc has deemed appropriate (e.g. application/pdf, text/plain, application/octet, etc.). However, if there is an error the response will return via the specified response type (XML or JSON) accompanied with an HTTP error code.

Sample Attachment Request: (Replace {X-Sendinc-Message-Id} & {attachment_id} with the correct values)

$ curl -u email@address.com:pass https://rest.sendinc.com/attachment/{X-Sendinc-Message-Id}/{attachment_id}.json

Error Handling

If the HTTP response code is not 200 then an error has occurred.

Example Error Server Response:

HTTP/1.1 401 Unauthorized

Often times, in addition to an HTTP error, the server will return error details in the response body. If error data is available in the response body it can be displayed to the client.

Example JSON Error Response:

{\n  
\"error\":[\n    
\"Couldn't authenticate you\"\n  
]\n
}

Example XML Error Response:

<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n  
<error>\n    
<element>Couldn't authenticate you</element>\n  
</error>

API Throttle

To ensure a consistent quality of service Sendinc may block users making a large number of requests over a short period of time. Most users will never come close to reaching this limit but if it is reached the server will return a 403 Forbidden response with an error message of “API Quota exceeded” in the standard XML/JSON error format. Developers should anticipate this error and handle accordingly.

Still have questions about the Sendinc REST API? 

Submit a Support Ticket