LiquidFiles Documentation
LiquidFiles Documentation
Updated v3.7

Sending Secure Messages

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

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

There is also an alternative method using Base64 and JSON based uploads. This is not the preferred method because Base64 encoding adds about 33% in size to the uploaded file and the overall limit for uploaded files are 100MB making the real file upload limit about 75MB and this is per message, not individual files. When using the binary upload method, there's no upload limit.

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.
sender String (Optional) if the user is permitted to send as another user, the alternate sending email can be set here.
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). Defaults to false if not present.
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
  • 4: Specified Recipients and Recipient Domains can download
attachments Array If we're using the binary upload method, 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 SHA256 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 binary 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":""\u003cdiv class=\"liquidfiles_attachments\"\u003e\n  \n  \u003ch4 style=\"margin: 0; padding: 0; border-top: 1px solid #c0c0c0; margin-top: 1.5em; padding-top: 1em;\"\u003eFiles attached to this message\u003c/h4\u003e\n\n  \u003ctable style=\"border-collapse: collapse; border: 5px solid #fff; margin: 1em; padding 0.3em; background-color: white;\"\u003e\n  \u003ctr\u003e\n    \u003cth style=\"padding: 0.4em 0.5em 0.2em 0.5em; border-bottom: 1px solid #C0C0C0;\"\u003eFilename\u003c/th\u003e\n    \u003cth style=\"padding: 0.4em 0.5em 0.2em 0.5em; border-bottom: 1px solid #C0C0C0;\"\u003eSize\u003c/th\u003e\n    \u003cth style=\"padding: 0.4em 0.5em 0.2em 0.5em; border-bottom: 1px solid #C0C0C0; color: #777;\"\u003eChecksum (SHA1)\u003c/th\u003e\n  \u003c/tr\u003e\n  \n    \u003ctr\u003e\n      \u003ctd style=\"padding: 0.4em 1em 0.4em 0.6em;\"\u003esecret_data.xls\u003c/td\u003e\n      \u003ctd style=\"padding: 0.4em 0.5em; text-align: right;\"\u003e361 Bytes\u003c/td\u003e\n      \u003ctd style=\"padding: 0.4em 0.5em; color: #777;\"\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=\"https://test.host/message/teIJfsihQpdc8UzUuaxKp7\"\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"",
      "plain":""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"",
      "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 unfortunately lacks support for raw text responses like "CDATA" in XML. This makes it somewhat 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 " 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.

Binary Upload Example using curl and bash

#!/bin/bash

api_key="nkpIxMK9ucUUE7FvfNpdAf"
server_url="https://liquidfiles.company.com"

attachment_id=`curl -X POST --user "ojubiigauS2TxTy4ovk6Ph:x" -H "Accept: application/json" \
  --data-binary "@/path/to/filename.ext" $server_url/message/attachments/upload?filename=filename.ext | jq .attachment.id`

cat <<EOF | \
  curl -k -X POST --user "$api_key:x" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -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":[$attachment_id]
  }
}
EOF
  • jq included in the example is a command line JSON parser that can extract in this case the attachment id from the JSON response to make it easier to include in subsequent requests.

Example using JSON based file uploads

Please note that the maximum message size is 100 MB using this method. Please use the binary upload method for larger files.

cat <<EOF | curl -s -X POST -H "Accept: application/json" -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.ext",
      "data":"IyMKIyBIb3N0IERhd ...Base64 encoded data... GFiYXNlCiMKIyBsb2NhbGhv==",
      "checksum":"38815a641c895e00832658033b0f1d67d3c06995",
      "crc32":"1999548066"
    }]
  }
}
EOF

Base64 Attachments Example using curl and bash

#!/bin/bash

api_key="nkpIxMK9ucUUE7FvfNpdAf"
server_url="https://liquidfiles.company.com"

filename=/path/to/filename.ext

cat <<EOF | curl -k -X POST -H "Accept: application/json" -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":"`sha256sum $filename | awk '{print $2}'`"
    }]
  }
}
EOF