Online Help Center > SendSafely APIs

SendSafely.js

SendSafely.js is the primary client side JavaScript API used to communicate with the SendSafely server platform.

SendSafely(url, apiKey, apiSecret)
Return Type: constructor
The only constructor for the library.
Parameters:
NameTypeDescription
url String The host which the API will connect to
apiKey String The API Key which will be used to connect to SendSafely
apiSecret String The private key used to verify the request
Raised Events: N/A

parseLinks(text)
Return Type: List
A helper function to parse out links from a String of text. Returns a list of links.
Parameters:
NameTypeDescription
text String The text to be parsed
Raised Events: N/A

verifyVersion(api_identifier, finished)
Return Type: void
Verifies the API version against the SendSafely server using the API Key.
Parameters:
NameTypeDescription
api_identifier String Not required. Third party applications should leave it as undefined or pass in 'JS_API'
finished function function( OK | UPGRADE_AVAILABLE | OUTDATED_VERSION )
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

verifyCredentials(finished)
Return Type: void
Verifies the API and secret key against the server. Returns the user email which is associated with the key.
Parameters:
NameTypeDescription
finished function function (email)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

enterpriseInfo(finished)
Return Type: void
Retrieves enterprise related information such as the hostname specific to the organization as well as the SendSafely name of the organization.
Parameters:
NameTypeDescription
finished function function(host, systemName)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

createPackage(finished)
Return Type: void
Returns a JSON object populated with meta data about the newly created package.
Parameters:
NameTypeDescription
finished function function (packageId, serverSecret, packageCode, keyCode)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

packageInformation(packageId, finished)
Return Type: void
Fetch the latest package meta data from the server and return it
Parameters:
NameTypeDescription
packageId String The packageId to fetch information for
finished function function (PackageInformation)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

packageInformationFromLink(link, finished)
Return Type: void
Fetch the latest package meta data from the server and return it
Parameters:
NameTypeDescription
link String The Secure Link to extract data from
finished function function (PackageInformation)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

encryptAndUploadFiles(packageId, keyCode, serverSecret, files, uploadType, finished)
Return Type: void
Encrypts and uploads a list of files to the server
Parameters:
NameTypeDescription
packageId String The unique packageId that you are adding the file to
keyCode String The key code associated with the package (required for calculating the correct encryption key)
serverSecret String The server secret associated with the package (required for calculating the correct encryption key)
files List[blob] An array of the files that are being requested to upload
uploadType String Optional Leave blank or specify 'JS_API'
finished function function (packageId, fileId, fileSize, fileName)
Raised Events:
EventSignatureDescription
sendsafely.progress function({fileId: String, percent: Number}) Subscribe to this event to receive upload progress.
file.upload.error function({fileId: String, message: String}) Raised when an upload error occurs.
sendsafely.files.attached function({fileId: String, name: String, size: Number, packageId: String})

encryptMessage(packageId, keyCode, serverSecret, message, finished)
Return Type: void
Encrypt a new message. This function will only encrypt the message, not upload it to the server.
Parameters:
NameTypeDescription
packageId String The unique packageId that you are adding the message to
keyCode String The keycode used to encrypt the message with
serverSecret String The server secret used to encrypt the message with
message String The message to be encrypted.
finished function function (encryptedMessage)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

encryptAndUploadMessage(packageId, keyCode, serverSecret, message, finished)
Return Type: void
Encrypts and uploads a message to the server.
Parameters:
NameTypeDescription
packageId String The unique packageId that you are adding the message to
keyCode String The keycode used to encrypt the message with
serverSecret String The server secret used to encrypt the message with
message String The message to be encrypted.
finished function function ()
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

saveMessage(packageId, message, finished)
Return Type: void
Syncs a message with the server.
Parameters:
NameTypeDescription
packageId String The unique packageId that you are adding the message to
message String The message to be uploaded.
finished function function ()
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

downloadFile(packageId, fileId, keyCode, config)
Return Type: void
Downloads and decrypts a given file.
Parameters:
NameTypeDescription
packageId String The unique packageId identifying the package
fileId String The file ID referencing the file which is to be downloaded
keyCode String The key code associated with the package (required for calculating the correct decryption key)
config Map Optional. A config object which can be used to override in what format and how the file is stored. See the Config object further down for more information.
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message
download.progress function({fileId: String, progress: Number}) Subscribe to this event to receive download progress.
file.decrypted function({fileId: String}) Raised when a file is decrypted and ready to be saved.
save.file function({fileId: String, file: Blob}) The raw decrypted file. Use this event to save the file to the actual file system

addRecipient(packageId, email, finished)
Return Type: void
Adds a recipient to a given package.
Parameters:
NameTypeDescription
packageId String The unique packageId that you are adding the recipient to
email String The recipient email to be added
finished function function (Recipient)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

addRecipientPhonenumber(packageId, recipientId, phonenumber, countryCode, finished)
Return Type: void
Updates a recipient by giving it a phone number.
Parameters:
NameTypeDescription
packageId String The unique packageId that you are updating
recipientId String The recipientId to which the phone number will be added.
phonenumber String A phone number to be assoicated with the recipient
countryCode String A country code associated with the phone number
finished function function()
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

finalizePackage(packageId, packageCode, keycode, finished)
Return Type: String
Finalizes the package so it can be delivered to the recipients. The URL is returned to the client. The keycode must be appended to the URL before it can be delivered to the recipients.
Parameters:
NameTypeDescription
packageId String The unique packageId that's being finalized
packageCode String The package code used to create the secure link.
keycode String The keycode used to encrypt the message and files.
finished function function (url)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

finalizeUndisclosedPackage(packageId, packageCode, keycode, password, finished)
Return Type: String
Finalizes the package so it can be delivered to the anyone that receives the link. The URL is returned to the client. The keycode must be appended to the URL before it can be delivered to the recipients.
Parameters:
NameTypeDescription
packageId String The unique packageId that's being finalized
packageCode String The package code used to create the secure link.
keycode String The keycode used to encrypt the message and files.
password String A password that will be required in order to access the package. Leave as undefined if no password should be required
finished function function (url)
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

deleteTempPackage(packageId, finished)
Return Type:
Deletes a temporary package
Parameters:
NameTypeDescription
packageId String The packageId that's being deleted
finished function function ()
Raised Events:
EventSignatureDescription
sendsafely.error function(code, message) Raised if an error happens. Code contains a response code originating from the server. Message is a more descriptive error message

PackageInformation
NameTypeDescription
packageId String N/A
packageCode String N/A
serverSecret String N/A
recipients List[Recipient] N/A
files List[File] N/A
approverList List[approverEmail] N/A
needsApproval bool N/A
state PackageState N/A
life Integer N/A
description String N/A

Recipient
NameTypeDescription
recipientId String N/A
email String N/A
needsApproval bool N/A

File
NameTypeDescription
fileId String N/A
fileName String N/A
fileSize Integer N/A

PackageState
NameTypeDescription
PACKAGE_STATE_DELETED_PARTIALLY_COMPLETE enum N/A
PACKAGE_STATE_DELETED_INCOMPLETE enum N/A
PACKAGE_STATE_TEMP enum N/A
PACKAGE_STATE_DELETED_COMPLETE enum N/A
PACKAGE_STATE_IN_PROGRESS enum N/A
PACKAGE_STATE_EXPIRED_INCOMPLETE enum N/A
PACKAGE_STATE_EXPIRED_COMPLETE enum N/A
PACKAGE_STATE_ACTIVE_COMPLETE enum N/A
PACKAGE_STATE_ACTIVE_INCOMPLETE enum N/A
PACKAGE_STATE_ACTIVE_PARTIALLY_COMPLETE enum N/A
PACKAGE_STATE_EXPIRED_PARTIALLY_COMPLETE enum N/A

Config
NameTypeDescription
storage function Override the default Storage mechanisms. SendSafely stores files split up into smaller segments at rest. The storage interface will be called every time a new segment is done encrypting. You can override this interface to customize how to store the decrypted data.

The default storage is defined as below:function DefaultStorage(eventHandler) {
  this.getFileFormat = function() {return "ARRAY_BUFFER"; // Can be "ARRAY_BUFFER", "BASE64" or a list containing both};

  this.store = function(fileId, part, data)
  {
    var settings = {}
    settings.type = "application/octet-stream";
    if(myself.file === undefined) {
      myself.file = new Blob([data], settings);
    } else {
      myself.file = new Blob([myself.file, data], settings);
    }
  };

  this.save = function(fileId)
  {
    var event = {};
    event.fileId = fileId;
    event.file = myself.file;
    eventHandler.raise("save.file", event);
  };
}
api String The API used to download the file. Will default to JS_API.