Sending files using the Filedrop

The Filedrop is the only API call that doesn't use authentication. The reason is that the Filedrop is used with unauthenticated uploads and will therefore don't need to be authenticated.

Filedrop Info Request

In order to make client side validation possible when sending through a Filedrop, you can start by running a Filedrop Info Request like this:

This will respond with details about the Filedrop that can be used to facilitate the Filetransfer (the Filedrop api key) and the file type and file size limitations so that you can implement client side validations of those without having to upload a file.

Example using curl with response

curl -k -H "Accept: application/json" -H "Content-Type: application/json" https://liquidfiles.company.com/filedrop/test_filedrop
{"filedrop":
  {
    "api_key":"qiXT9Za7HcXhMTJDBo2oe5",
    "name":"Filedrop Test",
    "limited_extensions":"doc, docx, xls, xlsx, ppt, pptx, png, gif, jpg, jpeg, pdf, zip",
    "blocked_extensions":"",
    "max_upload_size":250
  }
}

Some depcreated parameters might still be visible. Please only use these as deprecated parameters will be removed.

Sending Files

The sending of files is very similar to the sending messages API, with the only real change is that the Filedrop API key is included in the form data. For instructions how to to upload the file(s), please see the Attachments API. The API key in this instance refers to the Filedrop API key. If you go to Admin → Filedrop and click on the Filedrop you want to use with the API, it will list its API key, or you can use the Filedrop Info request above to retrieve the Filedrop API key.

Please note that it's not possible to use User Filedrops with the API.

The easiest to illustrate is probably with an example, using curl

#!/bin/bash

# Some variables
filedrop_server=https://liquidfiles.company.com
filedrop_url=$filedrop_server/filedrop/filedrop_test

# retrieve the Filedrop API key
filedrop_api_key=`curl -H "Accept: application/json" -H "Content-Type: application/json" $filedrop_url | ruby -rjson -e 'puts JSON.parse(STDIN.read)["filedrop"]["api_key"]'`

# Send the file
attachment_id=`curl -X POST -F Filedata=@bigfile.zip --user "$filedrop_api_key:x" $filedrop_server/attachments`

cat <<EOF | curl -s -X POST -H "Accept: application/json" -H "Content-Type: application/json" -d @- $filedrop_url
{"message":
  {
    "from":"someone@somewhere.com",
    "subject":"test subject",
    "message":"Please let me know what you think!",
    "attachments":["$attachment_id"]
  }
}
EOF

The purpose of the Filedrop api key is authenticate the upload and to provide some protection. On the web interface, there's other protections like authorization tokens that prevents someone from automating an attack (the authorization token needs to be fed back to the server.

Response

The Filedop API response is basically a simple OK message that the message has been delivered ok. You can also check for HTTP status code 200. If everything is ok, you should see the following output:

{"message":{"status":"Filedrop message sent successfully"}}

If there's an error, you will see a standard JSON error message like:

{"errors":["You need to attach at least one file"]}

Deprecated responses in API v4

The following API responses are still available in LiquidFiles v3.0.x and will be removed for version 3.2.

The Example above is only listing the current api responses, in LiquidFiles v3.0.x, the following will be listed as well: