Interfacing with the Sendinc REST API
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.
Have code samples you’d like to share? You rock! Please feel free to contribute your sample code on our developer forums.
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:
{
"account":
{
"email": "email@address.com",
"first_name": "Bill",
"last_name": "Lumbergh",
"date_created": "2011-07-11 18:01:22",
"type": "pro",
"max_messages_per_day": 200,
"max_recipients": 100,
"max_attachment_size": 209715200
}
}
Sample XML Response:
<account> <date_created>2011-07-11 18:01:22</date_created> <email>email@address.com</email> <first_name>Bill</first_name> <last_name>Lumbergh</last_name> <max_attachment_size>209715200</max_attachment_size> <max_messages_per_day>200</max_messages_per_day> <max_recipients>100</max_recipients> <type>pro</type> </account>
Sending a Message
Sending a message involves a POST command to /message.json or /message.xml using the parameters in the following table:
| Parameter | Description | Required | Default Value |
|---|---|---|---|
|
|
Sender email. (Must match Sendinc user unless Corporate user) |
Yes |
|
|
recipients |
Recipients. Separated by commas. |
Yes |
|
|
recipients_cc |
CC recipients. Separated by commas. |
No |
|
|
recipients_bcc |
BCC recipients. Separated by commas. |
No |
|
|
subject |
Message Subject |
No |
|
|
message |
Body of message. Parsed as plain text for Basic accounts, HTML for Pro/Corporate. |
No* |
|
|
copy_me |
Send a copy of the message to the sender. |
No |
0 (false) |
|
notify |
(Pro/Corporate Only) Receive an email notification when a recipient opens your message. |
No |
0 (false) |
|
expire_when_read |
(Pro/Corporate Only) Set the message to expire after the recipient reads it. |
No |
0 (false) |
|
expires |
(Pro/Corporate Only) Set an expiration date (in days) for your message to expire. Valid ranges include 1-365 days and 0 for no expiration date. |
No |
7 for Basic accounts, 0 (never) for Pro/Corporate |
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 \ -X POST \ -F "message=Message Body" -F "email=email@address.com" \ -F "recipients=recipient@address.com,another@address.com" \ -F "recipients_cc=carbonrecipient@address.com" \ -F "subject=My Subject" \ -F att_0=@document.pdf -F att_1=@sourcecode.cpp \ 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:
{
"message":
{
"body":"Did you get the memo about this?",
"subject":"TPS Reports",
"sender_name":"Bill Lumbergh",
"sender_email":"bill@initech.com",
"created":1313619886,
"expires":1316211886,
"recipient":"peter@initech.com",
"recipients":{
"to":[
"peter@initech.com"
],
"cc":[
"dom@initech.com",
"bob@initech.com"
]
},
"attachments":[
{
"id":0,
"name": "newtpsreportcoversheetmemo.doc",
"short_name":"newtpsreportcovershe...o.doc",
"icon":"doc.png",
"size":71168,
"content_type":"application/msword"
}
]
}
}
Sample XML Reponse:
<message> <attachments> <element> <content_type>application/msword</content_type> <icon>doc.png</icon> <id>0</id> <name>newtpsreportcoversheetmemo.doc</name> <short_name>newtpsreportcovershe...o.doc</short_name> <size>71168</sizeor drag and drop files
Carlos Rios
Comments