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.

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 -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":[$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