REST API

Interfacing with the Sendinc REST API

Written By Marissa Fegan (Super Administrator)

Updated at July 31st, 2024

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.

Create a New Request

  1. Click on "New" to create a new request
  2. Select "Request" from the options
  3. Name your request (e.g., "Sendinc API Test") and select a collection to save it to, or create a new collection

Authenticate Your Requests

Sendinc API uses HTTP Basic Authentication. You'll need to add your Sendinc Email Alias and Password to the request.

  1. In the request window, select the "Authorization" tab
  2. Choose "Basic Auth" from the Type dropdown
  3. Enter your Sendinc email and password in the Username and Password fields

Test the API Endpoints

  1. Get Account Information
  2. In Postman, set the method to “GET”
  3. Enter the URL: https://rest.sendinc.com/account.json
  4. Click on Send
  5. Check the response
    • You should get a JSON response with your account details
  6. Send a Message
  7. In Postman, set the method to “POST”
  8. Enter the URL: https://rest.sendinc.com/message.json
  9. Select the "Body" tab and choose form-data
  10. Add the required parameters:
    • email: Your Sendinc email
    • recipients: Recipient's email
    • message: Body of the message
  11. Click on Send
  12. Check the response. It should be empty if successful
  13. Retrieve a Message
  14. In Postman, set the method to “GET”
  15. Enter the URL: https://rest.sendinc.com/message/{message_id}.json (replace {message_id} with the actual message ID)
  16. Click on Send
  17. Check the response; you should get a JSON response with the message details
  18. Download an Attachment
  19. Endpoint: GET https://rest.sendinc.com/attachment/{X-Sendinc-Message-Id}/{attachment_id}.json
  20. In Postman, set the method to GET
  21. Enter the URL: https://rest.sendinc.com/attachment/{X-Sendinc-Message-Id}/{attachment_id}.json (replace {X-Sendinc-Message-Id} and {attachment_id} with the actual values)
  22. Click on Send
  23. Check the response. You should get the attachment if successful.

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:

Parameter Description Required Default Value
email 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 \\\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>

Note

  • The message body will be returned in HTML, even for messages that were submitted in plain-text (new lines will be converted to , etc)
  • The recipient field displays the viewing recipient for the message. This is typically the same as the email address you are logged in as unless you are masquerading in your Sendinc Corporate account.
  • The icon value returned in the attachment section of a message refers to the suggested icon image to display if rendering the message inside a web application. The file-type icons Sendinc uses can be downloaded here.
  • You can download the message as a PDF instead of JSON/XML by appending ?pdf=1"
 

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>

Warning

There may be more than one error in the `error` element.

 

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