API

Software developers can create extras and add-ons with the safedrop API. Carry on reading to find out how it works, and how you can add value to your systems by integrating with safedrop.

The safedrop API is implemented as a RESTful HTTP web service. You can explore the web service using a command line HTTP client, such as the excellent http-console (http://github.com/cloudhead/http-console).

Authentication

When youʼre using the API, itʼs always through an existing user in safedrop. Thereʼs no special API user. Authentication requires an API key, which youʼll find on your account details page in safedrop.

In order to authenticate, you need to send your email address and API key to our authentication server, https://auth.api.safedrop.com, which will return a temporary authentication token you can use to access the API.

The authentication service differs from the rest of the API in that data is passed and returned in custom HTML headers. You must send your email address in an X-Auth-User header, and your API key in the X-Auth-Key header. The service will return the temporary authentication token in the X-Auth-Token header.

Example authentication request and response:

GET / HTTP/1.1
Host: auth.api.safedrop.com
X-Auth-User: joeuser@joeuser.com
X-Auth-Key: 6dfb44dae882655cfbf1d10bd3252d315054b48a

HTTP/1.1 204 No Content
[..]
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

When making requests to the safedrop API, you must supply your authentication token using an X-Auth-Token header.

Note that authentication tokens are valid for a limited time period. When the token has expired, any further API requests will return a 401 Unauthorized response. In order to continue using the API, you must re-authenticate and obtain a new token.

Actions

Note: a full API reference for the fields shown in the example messages in this section is in the next section.

List safedrops

Performing a GET on https://api.safedrop.com/dropbundles will return a list of all of your safedrops.

GET /dropbundles HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

[
    {
        read_remove: true,
        allow_comments: false,
        secure_message: false,
        expiry_date: '2011-04-01T10:00:00Z',
        require_token_auth: false,
        message: '',
        id: 2984,
        email_receipt_when: 4,
        subject: ''
    },
    {
        read_remove: true,
        allow_comments: false,
        secure_message: false,
        expiry_date: '2011-04-01T10:13:24Z',
        require_token_auth: false,
        message: '',
        id: 4661,
        email_receipt_when: 4,
        subject: 'testbigfiles'
    }
]

Create a safedrop

POST /dropbundles HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

message=Lorem+ipsum+dolor+sit+amet%2C+consectetur+adipisicing+elit%2C+sed+do+eiusmod+tempor+incididunt+ut+labore+et+dolore+magna+aliqua.&subject=Lorem+Ipsum

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

{
    read_remove: true,
    allow_comments: false,
    secure_message: false,
    expiry_date: '2011-04-01T10:35:53Z',
    require_token_auth: false,
    message: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
    id: 5740,
    email_receipt_when: 4,
    subject: 'Lorem Ipsum'
}

Show a safedrop

GET /dropbundles/5740 HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

{
    read_remove: true,
    allow_comments: false,
    secure_message: false,
    expiry_date: '2011-04-01T10:35:53Z',
    require_token_auth: false,
    message: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
    id: 5740,
    email_receipt_when: 4,
    subject: 'Lorem Ipsum'
}

Update a safedrop

PUT /dropbundles/5740 HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

require_token_auth=1

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

{
    read_remove: true,
    allow_comments: false,
    secure_message: false,
    expiry_date: null,
    require_token_auth: true,
    message: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
    id: 5740,
    email_receipt_when: 4,
    subject: 'Lorem Ipsum'
}

List recipients of a safedrop

GET /dropbundles/5740/dropbundlerecipients HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

[

   {
        id: 6877,
        telephone: '',
        valid_for: 0,
        email: 'john@safedrop.com'
    },
    {
        id: 6876,
        telephone: '',
        valid_for: 0,
        email: 'mary@safedrop.com'
    }
]

Add a recipient to a safedrop

POST /dropbundles/5740/dropbundlerecipients HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

email=fred%40safedrop.com

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

{
    id: 6878,
    telephone: '',
    valid_for: 0,
    email: 'fred@safedrop.com'
}

Show a recipient

GET /dropbundles/5740/dropbundlerecipients/6878 HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

{
    id: 6878,
    telephone: '',
    valid_for: 0,
    email: 'fred@safedrop.com'
}

Update a recipient

PUT /dropbundles/5740/dropbundlerecipients/6878 HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

telephone=442077394252

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

{
    id: 6878,
    telephone: '442077394252',
    valid_for: 0,
    email: 'fred@safedrop.com'
}

List files on a safedrop

GET /dropbundles/5740/dropfiles HTTP/1.1
Host: api.safedrop.com
X-Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

[
    {
        id: 7924,
        the_file: 'file1.txt'
    },
    {
        id: 7925,
        the_file: 'file2.txt'
    }
]

Add a file to a safedrop

POST /dropbundles/5740/dropfiles HTTP/1.1
Host: api.safedrop.com
Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c
Content-type: multipart/form-data; boundary=def46f21fc67

--def46f21fc67
content-disposition: form-data; name="the_file"; filename="file1.txt"
Content-Type: text/plain

[..]

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

{
    id: 7926,
    the_file: 'file1.txt'
}

Show a file

GET /dropbundles/5740/dropfiles/7926
HTTP/1.1
Host: api.safedrop.com
Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

HTTP/1.1 200 OK
[..]
Content-Type: application/json; charset=utf-8

{
    id: 7926,
    the_file: 'file1.txt'
}

Send the safedrop to all recipients

Once you’ve added recipients and files to your safedrop, this command will send out notification emails to all of the recipients and make the files available for download.

Once a safedrop has been sent, you will no longer be able to modify any of its properties or any properties of its recipients or files via the API.

GET /dropbundles/5740?send
HTTP/1.1
Host: api.safedrop.com
Auth-Token: 4079a0f5-06b3-4e5f-bdc6-bbab2156b67c

HTTP/1.1 200 OK
[..]
Content-Type: text/plain

OK

Reference

Methods

The safedrop API makes use of HTTP verbs to differentiate between different types of requests. In order to read or list resources, you use GET. In order to create a resource, you use POST. Resources are updated using PUT.

When you make a request and the resource does not support the method you have used, it will respond with a “405 Method Not Allowed” error code.

Data

PUT and POST methods accept form-encoded data representing key-value pairs of resource properties. An enctype of multipart/form-data should be used when using PUT or POST in a request that contains file data.

Date types are expressed in RFC3339 format, like "2010-12-19T16:39:57-08:00". Boolean types are expressed as 0 for false and 1 for true. The API will accept string values that contain UTF8 characters, assuming they are correctly URL encoded.

Data is returned from the service in JSON format.

Resources

All requests made to the web service must be over HTTPS using HTTP/1.1

https://auth.api.safedrop.com is the authentication server.

https://api.safedrop.com is where all the safedrop resources are addressable.

The resources addressable through the API have various properties that the web service client is able to create (or modify) before sending the safedrop. These properties mostly mirror the options available on the “compose” page on the safedrop website.

safedrops
subject Subject (optional)
message Message (optional)
secure_message Secure message attachment (optional)
Note: the contents of the secure message will not be returned from GET requests, only a boolean flag that indicates whether or not a secure message has been set.
expiry_date Expiry date (optional)
Note: when no expiry date is specified, the safedrop will never expire.
email_receipt_when Controls how receipts are sent out by the system (optional, default: 4)
  • 0 - disable email receipts
  • 1 - send an email every time a recipient downloads a file
  • 4 - send an email only the first time each recipient views the safedrop
Note: this only effects read receipts. Reply notifications and expiry summary emails will be sent regardless of the value of this property.
password When set, recipients will have to enter the password to access the safedrop (optional)
Note: the password will not be returned from GET requests.
read_remove Enable self destruct mechanism (optional, default: true)
allow_comments Enable secure replies (optional, default: false)
Note: read_remove and allow_comments flags are mutually exclusive. Also, this flag will only take effect when require_token_auth (below) is also enabled.
require_token_auth Enable token authentication (optional, default: false)
Note: by default, email token authentication is used. recipients that have telephone numbers set will use SMS token authentication.
Recipients
email Email address (required)
telephone Telephone number (optional)
Note: telephone numbers must be supplied in international dialling format, but without the leading ‘+’ symbol. Example: ‘442077394252’ for a British number. Recipients that have telephone numbers supplied will use SMS token authentication.
valid_for Validity period of the safedrop, in seconds (optional)
DEPRECATED - please use the expiry_date property on the dropbundle resource instead
Files
the_file File data (required)
Note: GET requests will return the name of the uploaded file only - file contents cannot be downloaded using the API.

HTTP error codes

A 400 "Bad Request" will be returned in response to a PUT or POST request on a resource when the form encoded properties do not meet requirements.

A 401 "Unauthorized" will be returned if the X-Auth-Token in the request is invalid or if an authorization request fails.

A 404 "Not Found" will be returned in response to a request for a resource (via an id in the URI) that doesn't exist.

A 405 "Method Not Allowed" will be returned if a HTTP method is not supported by the resource in its current state.

Feedback

If you have any comments or questions regarding the safedrop API, please contact us at