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 not 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 URL: /filedrop/_the_filedrop_
Request VERB: GET
Response:
  filedrop:
    api_key                # String.  The Filedrop API key, this is used to authenticate uploads.
    name                   # String.  The name of the Filedrop.
    accepted_filetypes     # String.  A comma separated list of accepted filetypes, if configured.
    invalid_extensions     # String.  A comma separated list of blocked file extensions, if configured.
    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: text/xml" https://liquidfiles.company.com/filedrop/test_filedrop
<?xml version="1.0" encoding="UTF-8" ?>
<filedrop>
  <api_key>m3Ajg9KdluLTqCK9roqVQ7</api_key>
  <name>Filedrop Test</name>
  <accepted_filetypes>doc, docx, xls, xlsx, ppt, pptx, png, gif, jpg, jpeg, pdf, zip</accepted_filetypes>
  <invalid_extensions></invalid_extensions>
  <max_upload_size type="integer">1000</max_upload_size>
</filedrop>

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 -s -H "Content-Type: text/xml" $filedrop_url | ruby -e 'puts STDIN.read.match(/\<api_key\>(.*)\<\/api_key\>/)[1]'`

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

cat <<EOF | curl -s -X POST -H 'Content-Type: text/xml' -d @- $filedrop_url
<?xml version="1.0" encoding="UTF-8"?>
<message>
  <api_key>$filedrop_api_key</api_key>
  <from>someuser@somecompany.com</from>
  <subject>Subject</subject>
  <message>Please let me know what you think!</message>
  <attachments type='array'>
    <attachment>$attachment_id</attachment>
  </attachments>
</message>
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. In v2.4.4 and earlier, there's no message if the message has been delivered ok, you can check for HTTP status code 200. In v2.4.5 and later, the following message will be sent when the Filedrop message has been delivered:

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>Filedrop message sent successfully</status>
</message>

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

<?xml version="1.0" encoding="UTF-8" ?>
<errors>
  <error>Some error message</error>
</errors>