LiquidFiles Documentation
LiquidFiles Documentation

Sending Files

Deprecation Notice

The XML API is only fully functional on LiquidFiles v2.x that is End of Life and End of Support.

This XML API has been deprecated in favour of the JSON API that's available in LiquidFiles v3.x onwards.

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