LiquidFiles Documentation
LiquidFiles Documentation

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:

Request Info
Info Value
Request URL /filedrop/_the_filedrop_
Request VERB GET
Response Parameters
Parameter Type Description
api_key String The Filedrop API key, this is used to authenticate uploads. Please note that this is not a persistent API key so you can't count on reusing this over and over again.
name String The name of the Filedrop.
limited_extensions String A comma separated list of accepted file extensions. If configured these are the only permitted file extensions you can send through this Filedrop.
blocked_extensions String A comma separated list of blocked file extensions. If configured these file extensions are not permitted when using this Filedrop. Please note that either limited_extensions or blocked_extensions can be configured, but never both at the same time.
max_upload_size Integer The maximum file size that will be accepted by the Filedrop in Megabytes.

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"
    "name":"Filedrop Test",
    "limited_extensions":"doc, docx, xls, xlsx, ppt, pptx, png, gif, jpg, jpeg, pdf, zip",

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.

Request Info
Info Value
Request URL /filedrop/_the_filedrop_
Request Parameters
Parameter Type Description
from String The email address of the sender.
subject String The Filedrop Subject.
message String The Filedrop Message.
attachments Array An array of all uploaded attachment_id's.

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


# Some variables

# 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(["filedrop"]["api_key"]'`

# Send the file
attachment_id=`curl -X POST -F --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
    "subject":"test subject",
    "message":"Please let me know what you think!",

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.


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:

Old Parameter New Parameter Description
invalid_extensions blocked_extensions Direct replacement.
accepted_filetypes limited_extensions Direct replacement.
max_filesize max_upload_size Direct replacement.