https://man.liquidfiles.com
LiquidFiles Documentation

The most common use of the API is to use it to send files.

Sending files with LiquidFiles is a two step process. First you have to upload the files you want to send using the Attachments API, and then you can attach the uploaded Attachments to the Message using the API calls on this page.

The message request

Request URL: /message
Request VERB: POST
Parameters:
message:
recipients: # Array The recipients email addresses
cc # Array (optional) The cc'd recipients
bcc # Array (optional) The bcc'd recipients
subject # String The subject of the message
message # String The body of the message
expires_at # Date When the message should expire in iso format (YYYY-mm-dd)
expires_after # Integer The number of times the message attachments will be permitted to be downloaded.
# If download permissions is set to anyone this is a global counter, if set to
# any other download permission this is a counter per recipient.
send_email # Boolean True means that the LiquidFiles system will send the message to the recipients.
# False means that the LiquidFiles system won't send the message.
bcc_myself # Boolean True will send a copy to the sender. It defaults to true if not present.
private_message # Boolean True sets the private message option.
authorization # Integer 0: Anyone can download
# 1: Anyone can download after authentication
# 2: Specified Recipients and local users can download
# 3: Only Specified Recipients can download
attachments # Array If we're using the html form based upload, we're sending the message id's
# If we're using XML based file upload we send each file with the following
# parameters
filename # String The file name
data # String The raw file data in Base64 encoding
content_type # String The content-type for the file (will be guessed if not present)
checksum # String The SHA1 checksum for the file (will be calculated if not present)
crc32 # String The crc32 checksum for the file (will be calculated if not present)

Response:
message:
id # String The message ID
url # String The URL to the message
expires_at # Date When the message expires in iso format (YYYY-mm-dd)
expires_after # Integer How many times each attachment will be permitted to be downloaded.
authorization # Integer Who can download these files (see request for what number 0-3 means)
authorization_description # String Description of the authorization permissions
plain # String Complete message to be included when sending the message in plain text
html # String Complete message to be included when sending the message in simple html format

Example using xml based file uploads

Please note that the maximum message size is 100 Mb using this method. Pleas use the html form based upload method for larger files.

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <recipients type="array">
    <recipient>user1@company1.com
    <recipient>user2@company2.com
  </recipients>
  <cc type="array">
    <cc>user3@company3.com
    <cc>user4@company4.com
  </cc>
  <bcc type="array">
    <bcc>boss@example.com
  </bcc>
  <expires_at>2013-01-29
  <expires_after>5
  <subject>test subject
  <message>test message
  <attachments type='array'>
    <attachment>
      <filename>medium_size_file.ext
      <data>IyMKIyBIb3N0IERhd ..... GFiYXNlCiMKIyBsb2NhbGhv==
      <checksum>38815a641c895e00832658033b0f1d67d3c06995
      <crc32>1999548066
    </attachment>
  </attachments>
  <send_email>true
  <authorization>3
  <bcc_myself>false
</message>
      

Example using html form based file uploads

Using this method, we have already sent the files as outlined above, and we're just referencing the attachments when sending the message.

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <recipients type="array">
    <recipient>user1@company1.com</recipient>
    <recipient>user2@company2.com</recipient>
  </recipients>
  <cc type="array">
    <cc>user3@company3.com</cc>
    <cc>user4@company4.com</cc>
  </cc>
  <bcc type="array">
    <bcc>boss@example.com</bcc>
  </bcc>
  <expires_at>2013-01-29</expires_at>
  <subject>test subject</subject>
  <message>test message</message>
  <attachments type='array'>
    <attachment>12345</attachment>
    <attachment>2346</attachment>
  </attachments>
  <send_email>true</send_email>
  <authorization>3</authorization>
  <bcc_myself>false</bcc_myself>
</message>
	

Example Response

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <id>5jszBCG</id>
  <url>https://liquidfiles.example.com/message/Ofm7B0AD059OC31THvMH3z</url>
  <expires_at type="date">2013-01-29</expires_at>
  <expires_after type="integer"></expires_after>
  <authorization>3</authorization>
  <authorization_description>Only specified recipients can download</authorization_description>
  <html>
<![CDATA[
<div class="liquidfiles_attachments">
<p>The following files are attached to this message:</p>
<ul>
  <li>secret_data.xls (11.04 KB)</li>
</ul>

<p>Please visit the following url to download the attachments:</p>
<p>https://liquidfiles.example.com/message/Ofm7B0AD059OC31THvMH3z</p>

<p>The attachments are available until 2013-01-29.</p>
</div>
]]>
  </html>
  <plain>
<![CDATA[
The following files are attached to this message:
  - secret_data.xls (11.04 KB)

Please visit the following url to download the attachments:
https://liquidfiles.example.com/message/Ofm7B0AD059OC31THvMH3z

The attachments are available until 2013-01-29.
]]>
  </plain>
</message>
      

There's a few things to note about this response and what you can do with it:

  • If you want to include the html or plain response, feel free to do so.
  • If you don't, you can just roll your won and just grab the URL from the reponse. Browsing to this URL is how the recipients is going to download the files.
  • You can edit the API reponse messages in Admin → Email Templates → API template.

Complete sending example using curl

Using a simple unix shell script and curl, we're sending a file bigfile.zip to joe@customer.com:

Please note the ”@” in @bigfile.zip in the example below. This is what tells curl to read the data and include the content from bigfile.zip instead of adding bigfile.zip as text string.

#!/bin/sh

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

# Uploading the actual file and get attachment id for each file
attachment_id=`curl -X POST --user "$api_key:x" -F Filedata=@bigfile.zip $server/attachments`

# Send the message
cat <<EOF | curl -s -X POST --user "$api_key:x" -H 'Content-Type: text/xml' -d @- $server/message
<?xml version="1.0" encoding="UTF-8"?>
<message>
  <recipients type="array">
    <recipient>joe@customer.com</recipient>
  </recipients>
  <bcc type="array">
    <bcc>$email</bcc>
  </bcc>
  <expires_at>2013-01-29</expires_at>
  <subject>Here's the secret image we talked about.</subject>
  <message>Please let me know what you think!</message>
  <attachments type='array'>
    <attachment>$attachment_id</attachment>
  </attachments>
  <send_email>true</send_email>
  <authorization>3</authorization>
</message>
EOF