Background

Deaddrop can be accessed programmatically through its API. This documentation describes how to create an integration with Deaddrop for machine-to-machine communication.

The API may evolve over time. Customers who have informed Sysctl that they are using the API will receive notifications prior to any upgrades or changes. This ensures that their software can be updated in advance of new deployments.

API Users

To access the API, a user account with the API role must be created. This account will authenticate with Deaddrop using Basic Authentication.

When creating the account, the user must still include an email address (used as the username) and a mobile number. The mobile number does not need to be real, but it must follow the correct format.

After the account has been created, an API key must be assigned to the user.

The user can be created using the following commands:

/opt/sysctl/deaddrop/admscripts/add_account.pl api@sysctl.se 46123456789 api
htpasswd -bBC6  /var/deaddrop/html/api\@sysctl.se/.htpasswd api@sysctl.se API_KEY

Workflows

The API supports multiple workflows, such as sending a file to a receiver or granting a contact temporary access to Deaddrop. You can also retrieve history and other related information.

All data exchanges—except for file uploads and downloads—use the JSON format.

Send a File to the Designated Receiver

Allow Contacts to Use Deaddrop for Sending Files

Get a List of Contacts

Removing Contacts

Removing contacts uses the same endpoint as adding contacts. The API accepts a list of contacts to replace the existing ones.

To remove all contacts, send an empty JSON array ([]) in the request body.

Remove a Contact as a Receiver

Removing a contact as a receiver uses the same endpoint as adding receiver contacts. The API expects a list of receiver contacts to replace the existing ones.

To remove all receiver contacts, send an empty JSON array ([]) in the request body.

Remove an Uploaded File

Get History and Active Downloads

Download an Incoming File

API

  • Deaddrop uses Basic Authentication for all API requests.
  • All requests to the backend CGI endpoints must include a valid CSRF token.
  • To obtain a CSRF token for a user, send a GET request to the accounts index page. The token must then be extracted (parsed) from the response.
  • A CSRF token is valid for 15 minutes by default. This duration can be modified on the server.
  • Each valid request refreshes (resets) the token’s expiration time.
  • The username is typically a valid, lowercase email address.
  • A maximum of 60 concurrent CSRF tokens is allowed per user.
  • CSRF tokens are automatically deleted once they expire.

Get CSRF Token

A CSRF token is required for all CGI requests. It can be retrieved from the HTTP response when performing a GET request to a user’s index page.

The token value is contained in a hidden input field named csrftoken within the HTML response. This value must be extracted (parsed) and included in subsequent API requests.

Example:

<input type="hidden" id="csrftoken" name="csrftoken" value="1dJMRBNRMacGnfRzhpgda7Sq7eU=">

In the example above, the bolded value represents the CSRF token (1dJMRBNRMacGnfRzhpgda7Sq7eU=).

This CSRF token must be included in all CGI requests to the API. Requests without a valid token will be rejected.

Note: Don’t forget the trailing slash (/) in the request URL — it is required for the API to function correctly.

Description

Request

GET https://deaddrop.sysctl.se/apiuser@sysctl.se/

Response

index html code which include the CSRF token

Curl

curl -u apiuser@sysctl.se:apipassword https://deaddrop.sysctl.se/apiuser@sysctl.se/

Raw HTTP

> GET /apiuser@sysctl.se/ HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Wed, 11 Oct 2017 00:30:57 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 34287
< Content-Type: text/html; charset=utf-8
<
< <!DOCTYPE html>
< <html lang='en'>
< <head>
< ...
< ...
< </footer>
< <input type="hidden" id="refreshed" value="no"><input type="hidden" id="csrftoken" name="csrftoken" value="1dJMRBNRMacGnfRzhpgda7Sq7eU="></body></html>

Get Contacts

Before adding a contact, one needs to verify that the contact does not already exist. Adding a contact fails if it already exists.

Description

Request

GET https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/contacts_read.cgi

Response

json dictonary with arrays of local and global contact objects or empty arrays if no contacts exists

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" https://deaddrop.domain.se:443/apiuser@sysctl.se/cgi/contacts_read.cgi

Raw HTML

> GET /apiuser@sysctl.se/cgi/contacts_read.cgi HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
>
< HTTP/1.1 200 OK
< Date: Sat, 14 Oct 2017 03:17:09 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 105
< Content-Type: application/json; charset=utf-8
<
<{"local":[{"email":"contact@sysctl.se","number":"123456789","language":"en","groups":["sysctl"],"nick":"contact"}],"global":[]}

Add a Contact

To send a file to a receiver, at least one contact must be created. Contacts represent the recipients of files, but they can also be used to grant temporary access to Deaddrop functionality for a limited period.

Description

Request

POST https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/contacts_add.cgi
POST data: json array with contact

Response

json object with status code

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" -H "Content-Type: application/json" -X POST -d '[{"email":"contact@sysctl.se","number":"123456789","language":"en","groups":["sysctl"],"nick":"contact"}]' https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/contacts_add.cgi

Raw HTML

> POST /apiuser@sysctl.se/cgi/contacts_add.cgi HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
> Content-Type: application/json
> Content-Length: 105
>
> [{"email":"contact@sysctl.se","number":"123456789","language":"en","groups":["sysctl"],"nick":"contact"}]
>
< HTTP/1.1 200 OK
< Date: Wed, 11 Oct 2017 00:52:02 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 15
< Content-Type: application/json; charset=utf-8
<
< {"status":"ok"}

Add Contacts as Receivers

To send a dispatch to a receiver, at least one contact must be added as a receiver. One or more contacts can be assigned as receivers for a single file transfer.

Description

Request

POST https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/receivers_set.cgi
POST data: array with receiver(s)

Response

object with status code

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" -H "Content-Type: application/json" -X POST -d '[{"email":"contact@sysctl.se","number":"123456789","language":"en","groups":["sysctl"],"nick":"contact"}]' https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/receivers_set.cgi

Raw HTML

> POST /apiuser@sysctl.se/cgi/receivers_set.cgi HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
> Content-Type: application/json
> Content-Length: 105
>
> [{"email":"contact@sysctl.se","number":"123456789","language":"en","groups":["sysctl"],"nick":"contact"}]
>
< HTTP/1.1 200 OK
< Date: Wed, 11 Oct 2017 08:05:46 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 15
< Content-Type: application/json; charset=utf-8
<
< {"status":"ok"}

Get Uploaded Files List

Use this endpoint to retrieve a list of all files that have been uploaded.

Calling this endpoint also initializes the server-side list of uploaded files, which is required before any file can be shared with a receiver.

Description

Request

GET https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/get_files.cgi

Response

json array of objects or empty array if no file exists

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" https://deaddrop.domain.se:443/apiuser@sysctl.se/cgi/get_files.cgi

Raw HTML

> GET /testuser@sysctl.se/cgi/get_files.cgi HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
>
< HTTP/1.1 200 OK
< Date: Wed, 03 Oct 2018 19:48:00 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 71
< Content-Type: application/json; charset=utf-8
<
< [{"name":"gigfile","type":"application/octet-stream","size":"1.07 GB"}]

Delete an Uploaded File

To delete an uploaded file, first retrieve the list of uploaded files. Then, remove the desired file by sending a GET request with the filename specified as an argument.

Description

Request

GET https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/remove_file.cgi?filename=gigfile

Response

json status

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" https://deaddrop.domain.se:443/apiuser@sysctl.se/cgi/remove_file.cgi?filename=gigfile

Raw HTML

> GET /testuser@sysctl.se/cgi/remove_file.cgi?filename=gigfile HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
>
< HTTP/1.1 200 OK
< Date: Wed, 03 Oct 2018 19:48:00 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 20
< Content-Type: application/json; charset=utf-8
<
< {"status":"deldone"}

Upload a File

One or more files can be uploaded to Deaddrop. Uploaded files can then be shared with one or more receivers in a subsequent step.

File uploads must use the multipart/form-data content type.

Description

Request

POST https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/upload.cgi
do=upload
file data

Response

json object with status code

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" -F do=upload -F file=@/var/deaddrop/html/favicon.png https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/upload.cgi

Raw HTML

> POST /apiuser@sysctl.se/cgi/upload.cgi HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
> Content-Length: 2756
> Expect: 100-continue
> Content-Type: multipart/form-data; boundary=----------------------------9be544cb78fe
>
> data of file
>
< HTTP/1.1 100 Continue
< HTTP/1.1 200 OK
< Date: Wed, 11 Oct 2017 18:55:54 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Transfer-Encoding: chunked
< Content-Type: application/json; charset=utf-8
<
< {"status":"done"}

Create Dispatch

The dispatch operation sends the list of receivers along with the uploaded file(s) and associated POST data to the backend.

The backend processes this request and generates unique download pages for each receiver, allowing them to securely access the shared files.

Description

Request

POST https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/createdeaddrop.cgi
{"desttime":1,"ddmessage":"You have received this mail because you are allowed to download protected files delivered by the deaddrop service"}

Response

json object with status code

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" -H "Content-Type: application/json" -X POST -d '{"desttime":1,"ddmessage":"You have received this mail because you are allowed to download protected files delivered by the deaddrop service"}' https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/createdeaddrop.cgi

Raw HTML

> POST /apiuser@sysctl.se/cgi/createdeaddrop.cgi HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
> Content-Type: application/json
> Content-Length: 142
>
> {"desttime":1,"ddmessage":"You have received this mail because you are allowed to download protected files delivered by the deaddrop service"}
>
< HTTP/1.1 200 OK
< Date: Wed, 11 Oct 2017 19:03:42 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 15
< Content-Type: application/json; charset=utf-8
<
< {"status":"ok"}

Allow Contacts To Use Deaddrop

This functionality allows selected contacts to use Deaddrop to send files back to the originating user.

When this option is enabled, the contact receives temporary access to the Deaddrop upload interface. The access can be time-limited and configured when creating or updating the contact.

This enables two-way file exchange between users and their contacts while maintaining security and traceability.

Description

Request

POST https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/givedeaddrop.cgi
{"desttime":1,"ddmessage":"You have received this mail because you are allowed to use the deadddrop service"}

Response

json object with status code

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" -H "Content-Type: application/json" -X POST -d '{"desttime":1,"ddmessage":"You have received this mail because you are allowed to use the deadddrop service"}' https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/givedeaddrop.cgi

Raw HTML

> POST /apiuser@sysctl.se/cgi/givedeaddrop.cgi HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
> Content-Type: application/json
> Content-Length: 142
>
> {"desttime":1,"ddmessage":"You have received this mail because you are allowed to use the deadddrop service"}
>
< HTTP/1.1 200 OK
< Date: Wed, 11 Oct 2017 19:03:42 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 15
< Content-Type: application/json; charset=utf-8
<
< {"status":"ok"}

Get History

Use this endpoint to retrieve the history of created Deaddrops (shared files). It also returns a list of files that are available for download.

Description

Request

GET https://deaddrop.sysctl.se/apiuser@sysctl.se/cgi/get_history.cgi

Response

json object with status code

Curl

curl -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" https://deaddrop.domain.se:443/apiuser@sysctl.se/cgi/get_history.cgi

Raw HTML

> GET /testuser@sysctl.se/cgi/get_history.cgi HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< Date: Wed, 03 Oct 2018 20:56:49 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 1452
< Content-Type: application/json; charset=utf-8
<
< {"history":[{"deaddrop_type":"downloadfiles","create_time":"1538593281","ttl":"1","receivers":[{"email":"contact@sysctl.se","language":"en","number":"123456789","groups":["sysctl"],"nick":"contact"}],"ddmessage":"You have received this mail because you are allowed to download protected files delivered by the deaddrop service","sender":{"email":"testuser@sysctl.se","number":"46733755989","lang":"sv","first_run":"false","accountType":"perm","change_passwd":"false","settings":{"show_number":"true","show_email":"true","show_lang":"false","show_nick":"true"}},"files":[{"name": "favicon.png", "settings":"[]"}]},{"deaddrop_type":"downloadfiles","create_time":"1538600193","ttl":"1","receivers":[{"email":"testuser@sysctl.se","language":"en","number":"124456789","name":"","groups":["sysctl"],"nick":"testuser"}],"ddmessage":"You have received this mail because you are allowed to download protected files delivered by the deaddrop service","sender":{"email":"testuser@sysctl.se","number":"46733755989","lang":"sv","first_run":"false","accountType":"perm","change_passwd":"false","settings":{"show_number":"true","show_email":"true","show_lang":"false","show_nick":"true"}},"files":[{"name": "exfat.jpg", "settings":"[]"}]}],"live_deaddrops":"1","inbox":[{"ttl":"1","createtime":"1538600197","sender":"testuser@sysctl.se","files":[{"name":"exfat.jpg","settings":"[]"}],"url":"9e025a8b12526ef0eb0f79348abe9342c4cd107a909ddb4cea7ae44ff69890f8"}]}

Download a File

To download a file, first parse the JSON data returned by the Get History endpoint to retrieve the correct download URL.

The download URL structure and fields are described in the Data Format section. Once the URL is obtained, it can be used to initiate the file download.

Description

Request

GET https://deaddrop.sysctl.se/apiuser@sysctl.se/9e025a8b12526ef0eb0f79348abe9342c4cd107a909ddb4cea7ae44ff69890f8/files/exfat.jpg

Response

json status

Curl

curl -o exfat.jpg -u apiuser@sysctl.se:apipassword -H "CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=" https://deaddrop.domain.se:443/apiuser@sysctl.se/9e025a8b12526ef0eb0f79348abe9342c4cd107a909ddb4cea7ae44ff69890f8/files/exfat.jpg

Raw HTML

> GET /testuser@sysctl.se/9e025a8b12526ef0eb0f79348abe9342c4cd107a909ddb4cea7ae44ff69890f8/files/exfat.jpg HTTP/1.1
> Authorization: Basic YXBpdXNlckBzeXNjdGwuc2U6YXBpcGFzc3dvcmQ=
> Host: deaddrop.sysctl.se
> Accept: */*
> CSRF-Token: 1dJMRBNRMacGnfRzhpgda7Sq7eU=
>
< HTTP/1.1 200 OK
< Date: Wed, 03 Oct 2018 19:48:00 GMT
< Server: Apache
< Strict-Transport-Security: max-age=15768000
< Content-Security-Policy: default-src 'none'; script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self'; connect-src 'self'; child-src 'self'; object-src 'self';
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-UA-Compatible: IE=edge
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, must-revalidate
< Expires: 0
< Pragma: no-cache
< Content-Length: 20
< Content-Type: application/json; charset=utf-8
<
< [data not shown]

Data Format

Deaddrop uses JSON objects and arrays for all data communication between the client and the backend.

All request and response payloads—except for file uploads and downloads—must follow standard JSON formatting.

Contacts and Receivers

key value example
email email “email”:”contact@sysctl.se”
number number “number”:”123456789”
language string “language”:”en”
groups array of strings “groups”:[“group1”,”group2”]
nick string “nick”:”nickname”

Contact Example

{"email":"contact@sysctl.se","number":"123456789","language":"en","groups":["sysctl"],"nick":"contact"}

Receiver Example

{"email":"contact@sysctl.se","number":"123456789","language":"en","groups":["sysctl"],"nick":"contact"}

Create dispatch

key value example
desttime number “desttime”:1
ddmessage string “ddmessage”:”hello world”

Create Dispatch Example

{"desttime":1,"ddmessage":"You have received this mail because you are allowed to download protected files delivered by the deaddrop service"}

Response Message

The response message format may change in future versions of the API to adopt a more standardized and structured format.

Examples

{"status":"done"}
{"status":"deldone"}
{"status":"ok"}

History Response

{
	"history": [{
		"deaddrop_type": "downloadfiles",
		"create_time": "1538593281",
		"ttl": "1",
		"receivers": [{
			"email": "contact@sysctl.se",
			"language": "en",
			"number": "123456789",
			"groups": ["sysctl"],
			"nick": "contact"
		}],
		"ddmessage": "You have received this mail because you are allowed to download protected files delivered by the deaddrop service",
		"sender": {
			"email": "testuser@sysctl.se",
			"number": "46733755989",
			"lang": "sv",
			"first_run": "false",
			"accountType": "perm",
			"change_passwd": "false",
			"settings": {
				"show_number": "true",
				"show_email": "true",
				"show_lang": "false",
				"show_nick": "true"
			}
		},
		"files": [{
			"name": "favicon.png",
			"settings": "[]"
		}]
	}, {
		"deaddrop_type": "downloadfiles",
		"create_time": "1538600193",
		"ttl": "1",
		"receivers": [{
			"email": "testuser@sysctl.se",
			"language": "en",
			"number": "124456789",
			"name": "",
			"groups": ["sysctl"],
			"nick": "testuser"
		}],
		"ddmessage": "You have received this mail because you are allowed to download protected files delivered by the deaddrop service",
		"sender": {
			"email": "testuser@sysctl.se",
			"number": "46733755989",
			"lang": "sv",
			"first_run": "false",
			"accountType": "perm",
			"change_passwd": "false",
			"settings": {
				"show_number": "true",
				"show_email": "true",
				"show_lang": "false",
				"show_nick": "true"
			}
		},
		"files": [{
			"name": "exfat.jpg",
			"settings": "[]"
		}]
	}],
	"live_deaddrops": "1",
	"inbox": [{
		"ttl": "1",
		"createtime": "1538600197",
		"sender": "testuser@sysctl.se",
		"files": [{
			"name": "exfat.jpg",
			"settings": "[]"
		}],
		"url": "9e025a8b12526ef0eb0f79348abe9342c4cd107a909ddb4cea7ae44ff69890f8"
	}]
}

History and File Download Data Structure

The JSON response includes several key sections that describe existing Deaddrops, active downloads, and available files.

  • history - An array containing all previously created Deaddrops. Each entry represents a completed or shared transfer.
  • live_deaddrop - A numeric value indicating the number of currently active downloads.
  • inbox - An array containing metadata for each file that can be downloaded.

Downloading a File from the Inbox

To download a file listed in the inbox section:

  • The value of name represents the actual filename.
  • The url field provides the base download URL, which must be combined with the file path.
  • Files are stored in a subdirectory named files.

example:

https://deaddrop.sysctl.se/testuser@sysctl.se/9e025a8b12526ef0eb0f79348abe9342c4cd107a909ddb4cea7ae44ff69890f8/files/exfat.jpg

The request must include a valid CSRF token.

© Copyright sysctl Aktiebolag 2013-2025. All rights reserved