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 Info
Info Value
Request URL /message
Request VERB POST
Request Parameters
Parameter Type Description
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 (if you want to post the message URL yourself somewhere else).
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 JSON based file upload we send each file with the following parameters
  • filename: The file name
  • data: The raw file data in Base64 encoding
  • content_type: The content-type for the file (will be guessed if not present)
  • checksum: The SHA1 checksum for the file (will be calculated if not present)
  • crc32: The crc32 checksum for the file (will be calculated if not present)
Response Parameters
Parameter Type Description
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 parameters 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 JSON 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.

cat <<EOF | curl -s -X POST -H 'Content-Type: application/json' --user "nkpIxMK9ucUUE7FvfNpdAf:x" -d @- https://test.host/message
{"message":
  {
    "recipients":["someone@somewhere.com"],
    "subject":"test subject",
    "message":"Please let me know what you think!",
    "expires_at":"2017-01-30",
    "send_email":true,
    "authorization":3,
    "attachments":[{
      "filename":"medium_size",
      "data":"IyMKIyBIb3N0IERhd ...Base64 encoded data... GFiYXNlCiMKIyBsb2NhbGhv==",
      "checksum":"38815a641c895e00832658033b0f1d67d3c06995",
      "crc32":"1999548066"
    }]
  }
}
EOF

Complete Example using curl and bash

#!/bin/bash

api_key="nkpIxMK9ucUUE7FvfNpdAf"
server_url="https://lfapp.dev"

filename=/path/to/filename.ext

cat <<EOF | curl -k -X POST -H 'Content-Type: application/json' --user "$api_key:x" -d @- $server_url/message
{"message":
  {
    "recipients":["someone@somewhere.com"],
    "subject":"test subject",
    "message":"Please let me know what you think!",
    "expires_at":"2017-01-30",
    "send_email":true,
    "authorization":3,
    "attachments":[{
      "filename":"filename.ext",
      "data":"`openssl base64 -in $filename`",
      "checksum":"`openssl sha1 $filename | awk '{print $2}'`"
    }]
  }
}
EOF

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.

{"message":
  {
    "recipients":["someone@somewhere.com"],
    "subject":"test subject",
    "message":"Please let me know what you think!",
    "expires_at":"2017-01-30",
    "send_email":true,
    "authorization":3,
    "attachments":["FbVYZubSkVRYA6oQ8vNjBm", "5EtbAvUUqCsyUhE7j3PmL5"]
  }
}

Example Response

{"message":
  {
    "id":"teIJfsihQpdc8UzUuaxKp7",
    "url":"https://test.host/message/teIJfsihQpdc8UzUuaxKp7",
    "expires_at":"2017-01-30",
    "expires_after":0,
    "authorization":3,
    "authorization_description":"Only Specified Recipients can access",
    "private_message":false,
    "html":"&quot;\u003cdiv class=\&quot;liquidfiles_attachments\&quot;\u003e\n  \n  \u003ch4 style=\&quot;margin: 0; padding: 0; border-top: 1px solid #c0c0c0; margin-top: 1.5em; padding-top: 1em;\&quot;\u003eFiles attached to this message\u003c/h4\u003e\n\n  \u003ctable style=\&quot;border-collapse: collapse; border: 5px solid #fff; margin: 1em; padding 0.3em; background-color: white;\&quot;\u003e\n  \u003ctr\u003e\n    \u003cth style=\&quot;padding: 0.4em 0.5em 0.2em 0.5em; border-bottom: 1px solid #C0C0C0;\&quot;\u003eFilename\u003c/th\u003e\n    \u003cth style=\&quot;padding: 0.4em 0.5em 0.2em 0.5em; border-bottom: 1px solid #C0C0C0;\&quot;\u003eSize\u003c/th\u003e\n    \u003cth style=\&quot;padding: 0.4em 0.5em 0.2em 0.5em; border-bottom: 1px solid #C0C0C0; color: #777;\&quot;\u003eChecksum (SHA1)\u003c/th\u003e\n  \u003c/tr\u003e\n  \n    \u003ctr\u003e\n      \u003ctd style=\&quot;padding: 0.4em 1em 0.4em 0.6em;\&quot;\u003esecret_data.xls\u003c/td\u003e\n      \u003ctd style=\&quot;padding: 0.4em 0.5em; text-align: right;\&quot;\u003e361 Bytes\u003c/td\u003e\n      \u003ctd style=\&quot;padding: 0.4em 0.5em; color: #777;\&quot;\u003e\u003ctt\u003ecf5fa041042cda2b9754de8cd2ad910a07e95080\u003c/tt\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \n  \u003c/table\u003e\n  \u003cp\u003ePlease click on the following link to download the attachments: \u003ca href=\&quot;https://test.host/message/teIJfsihQpdc8UzUuaxKp7\&quot;\u003ehttps://test.host/message/teIJfsihQpdc8UzUuaxKp7\u003c/a\u003e\u003c/p\u003e\n\n  \n  \u003cp\u003eThis email or download link can not be forwarded to anyone else.\u003c/p\u003e\n  \n\n  \u003cp\u003eThe attachments are available until: \u003cb\u003eMonday, 30 January.\u003c/b\u003e\u003c/p\u003e\n  \u003cp\u003eMessage ID: teIJfsih\u003c/p\u003e\n\n\u003c/div\u003e\n&quot;",
    "plain":"&quot;The following files are attached to this message:\n\n\n  - secret_data.xls (361 Bytes), Checksum: cf5fa041042cda2b9754de8cd2ad910a07e95080\n\n\nPlease click on the following link to download the attachments:\nhttps://test.host/message/teIJfsihQpdc8UzUuaxKp7\n\n\nThis email or download link can not be forwarded to anyone else.\n\n\nThe attachments are available until: Monday, 30 January\n\nMessage ID: teIJfsih\n&quot;",
    "html_64":"PGRpdiBjbGFzcz0ibGlxdWlkZmlsZXNfYXR0YWNobWVudHMiPgogIAogIDxoNCBzdHlsZT0ibWFyZ2luOiAwOyBwYWRkaW5nOiAwOyBib3JkZXItdG9wOiAxcHggc29saWQgI2MwYzBjMDsgbWFyZ2luLXRvcDogMS41ZW07IHBhZGRpbmctdG9wOiAxZW07Ij5GaWxlcyBhdHRhY2hlZCB0byB0aGlzIG1lc3NhZ2U8L2g0PgoKICA8dGFibGUgc3R5bGU9ImJvcmRlci1jb2xsYXBzZTogY29sbGFwc2U7IGJvcmRlcjogNXB4IHNvbGlkICNmZmY7IG1hcmdpbjogMWVtOyBwYWRkaW5nIDAuM2VtOyBiYWNrZ3JvdW5kLWNvbG9yOiB3aGl0ZTsiPgogIDx0cj4KICAgIDx0aCBzdHlsZT0icGFkZGluZzogMC40ZW0gMC41ZW0gMC4yZW0gMC41ZW07IGJvcmRlci1ib3R0b206IDFweCBzb2xpZCAjQzBDMEMwOyI+RmlsZW5hbWU8L3RoPgogICAgPHRoIHN0eWxlPSJwYWRkaW5nOiAwLjRlbSAwLjVlbSAwLjJlbSAwLjVlbTsgYm9yZGVyLWJvdHRvbTogMXB4IHNvbGlkICNDMEMwQzA7Ij5TaXplPC90aD4KICAgIDx0aCBzdHlsZT0icGFkZGluZzogMC40ZW0gMC41ZW0gMC4yZW0gMC41ZW07IGJvcmRlci1ib3R0b206IDFweCBzb2xpZCAjQzBDMEMwOyBjb2xvcjogIzc3NzsiPkNoZWNrc3VtIChTSEExKTwvdGg+CiAgPC90cj4KICAKICAgIDx0cj4KICAgICAgPHRkIHN0eWxlPSJwYWRkaW5nOiAwLjRlbSAxZW0gMC40ZW0gMC42ZW07Ij5jcmVhdGVfdXNlcl9qc29uLnNoPC90ZD4KICAgICAgPHRkIHN0eWxlPSJwYWRkaW5nOiAwLjRlbSAwLjVlbTsgdGV4dC1hbGlnbjogcmlnaHQ7Ij4zNjEgQnl0ZXM8L3RkPgogICAgICA8dGQgc3R5bGU9InBhZGRpbmc6IDAuNGVtIDAuNWVtOyBjb2xvcjogIzc3NzsiPjx0dD5jZjVmYTA0MTA0MmNkYTJiOTc1NGRlOGNkMmFkOTEwYTA3ZTk1MDgwPC90dD48L3RkPgogICAgPC90cj4KICAKICA8L3RhYmxlPgogIDxwPlBsZWFzZSBjbGljayBvbiB0aGUgZm9sbG93aW5nIGxpbmsgdG8gZG93bmxvYWQgdGhlIGF0dGFjaG1lbnRzOiA8YSBocmVmPSJodHRwczovL2xmYXBwLmRldi9tZXNzYWdlL3RlSUpmc2loUXBkYzhVelV1YXhLcDciPmh0dHBzOi8vbGZhcHAuZGV2L21lc3NhZ2UvdGVJSmZzaWhRcGRjOFV6VXVheEtwNzwvYT48L3A+CgogIAogIDxwPlRoaXMgZW1haWwgb3IgZG93bmxvYWQgbGluayBjYW4gbm90IGJlIGZvcndhcmRlZCB0byBhbnlvbmUgZWxzZS48L3A+CiAgCgogIDxwPlRoZSBhdHRhY2htZW50cyBhcmUgYXZhaWxhYmxlIHVudGlsOiA8Yj5Nb25kYXksIDMwIEphbnVhcnkuPC9iPjwvcD4KICA8cD5NZXNzYWdlIElEOiB0ZUlKZnNpaDwvcD4KCjwvZGl2Pgo=",
    "plain_64":"VGhlIGZvbGxvd2luZyBmaWxlcyBhcmUgYXR0YWNoZWQgdG8gdGhpcyBtZXNzYWdlOgoKCiAgLSBjcmVhdGVfdXNlcl9qc29uLnNoICgzNjEgQnl0ZXMpLCBDaGVja3N1bTogY2Y1ZmEwNDEwNDJjZGEyYjk3NTRkZThjZDJhZDkxMGEwN2U5NTA4MAoKClBsZWFzZSBjbGljayBvbiB0aGUgZm9sbG93aW5nIGxpbmsgdG8gZG93bmxvYWQgdGhlIGF0dGFjaG1lbnRzOgpodHRwczovL2xmYXBwLmRldi9tZXNzYWdlL3RlSUpmc2loUXBkYzhVelV1YXhLcDcKCgpUaGlzIGVtYWlsIG9yIGRvd25sb2FkIGxpbmsgY2FuIG5vdCBiZSBmb3J3YXJkZWQgdG8gYW55b25lIGVsc2UuCgoKVGhlIGF0dGFjaG1lbnRzIGFyZSBhdmFpbGFibGUgdW50aWw6IE1vbmRheSwgMzAgSmFudWFyeQoKTWVzc2FnZSBJRDogdGVJSmZzaWgK"
  }
}

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. The html and plain reponses are generated using the api_response and api_private_message_response from Admin → Configuration → Email Templates.
  • JSON is generally considered to be superior to XML, and in most situations it is. One thing though is that JSON lacks support for "CDATA" - a way to include raw text responses like XML can. This makes it hard to include html response templates in the JSON output. As you can see, we include two versions. One "escaped" version (html and plain) where things like quotation marks have been replaced with &quot; and so on. And one Base64 encoded version (html_64 and plain_64). Base64 encoded is not human readable and can be easier to use if you want to include the output in your application.
  • If you don't want to use these html or plain responses, you can just roll your won and just grab the URL from the reponse. Browsing to the URL is how the recipients is going to download the files.