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

Request Info

Info	Value
Request URL	/filedrop/_the_filedrop_
Request VERB	POST

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

#!/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 "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 "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"]
  }
}

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:

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