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:
Info | Value |
---|---|
Request URL | /filedrop/_the_filedrop_ |
Request VERB | GET |
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" 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.
Info | Value |
---|---|
Request URL | /filedrop/_the_filedrop_ |
Request VERB | POST |
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 "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:
Old Parameter | New Parameter | Description |
---|---|---|
invalid_extensions | blocked_extensions | Direct replacement. |
accepted_filetypes | limited_extensions | Direct replacement. |
max_filesize | max_upload_size | Direct replacement. |