Start a conversation


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.


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.


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

XML Request:

$ curl -u

Sample JSON Response:

    "email": "",
    "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:

<?xml version="1.0" encoding="UTF-8"?>
    <date_created>2011-07-11 18:01:22</date_created>

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)




Recipients. Separated by commas.




CC recipients. Separated by commas.




BCC recipients. Separated by commas.




Message Subject




Body of message. Parsed as plain text for Basic accounts, HTML for Pro/Corporate.




Send a copy of the message to the sender.


0 (false)


(Pro/Corporate Only) Receive an email notification when a recipient opens your message.


0 (false)


(Pro/Corporate Only) Set the message to expire after the recipient reads it.


0 (false)


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


7 for Basic accounts, 0 (never) for Pro/Corporate


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 \
-F "message=Message Body" -F "" \
-F "," \
-F "" \
-F "subject=My Subject" \
-F att_0=@document.pdf -F att_1=@sourcecode.cpp \

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:

    "body":"Did you get the memo about this?",
    "subject":"TPS Reports",
    "sender_name":"Bill Lumbergh",
        "name": "newtpsreportcoversheetmemo.doc",

Sample XML Reponse:

<?xml version="1.0" encoding="UTF-8"?>
    <body>Did you get the memo about this?</body>
    <sender_name>Bill Lumbergh</sender_name>
    <subject>TPS Reports</subject>


  • The message body will be returned in HTML, even for messages that were submitted in plain-text (new lines will be converted to <br/>, 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 users 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{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:

    "Couldn't authenticate you"

Example XML Error Response:

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


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.


Choose files or drag and drop files
Was this article helpful?
  1. Carlos Rios

  2. Posted
  3. Updated