SendSafely

SendSafely(url, apiKey, apiSecret)

Return Type: constructor

The only constructor for the library.

Parameters:

Name	Type	Description
url	String	The SendSafely host/url that the API will connect to.
apiKey	String	The API Key that will be used to authenticate to SendSafely.
apiSecret	String	The API Secret that will be used to authenticate to SendSafely.

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 found in the provided text.

Parameters:

Name	Type	Description
text	String	The text to be parsed.

Raised Events: N/A

verifyCredentials(finished)

Return Type: promise

Verifies the API Key and API Secret with the server. Returns the email address of the user that owns the API key.

Parameters:

Name	Type	Description
finished	function	function (user)

Raised Events:

Event	Signature	Description
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

getUserInformation(finished, customErrorEvent)

Return Type: void

Returns profile information related to the authenticated API user.

Parameters:

Name	Type	Description
finished	function	function (user)
customErrorEvent	function	Optional custom error event (to replace user.information.failed).

Raised Events:

Event	Signature	Description
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

deleteFile(packageId, fileId, finished)

Return Type: void

Deletes a file from a package.

Parameters:

Name	Type	Description
packageId	String	The unique package id of the package for the delete file operation.
fileId	String	The unique file id of the file to delete.
finished	function	Optional callback function.

Raised Events:

Event	Signature	Description
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

removeRecipient(packageId, recipientId, finished)

Return Type: void

Removes a recipient from a given package.

Parameters:

Name	Type	Description
packageId	String	The unique package id of the package for the remove recipient operation.
recipientId	String	The unique recipient id of the recipient to remove from the package.
finished	function	optional callback function.

Raised Events:

Event	Signature	Description
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 organization-level information about the SendSafely enterprise account that the currently authenticated user belongs to.

Parameters:

Name	Type	Description
finished	function	function(host, systemName, allowUndisclosedRecipients, headerColor, linkColor, messageEncryption)

Raised Events:

Event	Signature	Description
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

addRecipient(packageId, email, keyCode, finished)

Return Type: void

Adds a recipient to a given package.

Parameters:

Name	Type	Description
packageId	String	The unique packageId that you are adding the recipient to.
email	String	The recipient email to be added.
keyCode	String	keyCode value of the package adding the recipient to.
finished	function	function (Recipient)

Raised Events:

Event	Signature	Description
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

addRecipients(packageId, emails, keyCode, finished, customErrorEvent)

Return Type: void

Adds a list of recipients to a given package.

Parameters:

Name	Type	Description
packageId	String	The unique package id of the package for the add recipient operation.
emails	String	The recipient email to be added.
keyCode	String	keyCode value of the package adding the recipient to.
finished	function	function (Recipient)
customErrorEvent	function	Optional custom error event (to replace recipients.add.failed).

Raised Events:

Event	Signature	Description
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

Adds a phone number to a recipient for SMS verification .

Parameters:

Name	Type	Description
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 used for SMS verification.
countryCode	String	A country code associated with the phone number.
finished	function	function ()

Raised Events:

Event	Signature	Description
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. Returns the Secure Link needed for recipients to access the package.

Parameters:

Name	Type	Description
packageId	String	The unique packageId that is 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:

Event	Signature	Description
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 a package without any recipients being specified. Returns the Secure Link needed for recipients to access the package.

Parameters:

Name	Type	Description
packageId	String	The unique packageId that is 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:

Event	Signature	Description
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 metadata for a specific package using a PackageId.

Parameters:

Name	Type	Description
packageId	String	The packageId of the package.
finished	function	function (PackageInformation)

Raised Events:

Event	Signature	Description
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
package.information.failed	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 metadata for a specific package using a Secure Link.

Parameters:

Name	Type	Description
link	String	The Secure Link for the package.
finished	function	function (PackageInformation)

Raised Events:

Event	Signature	Description
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

updatePackage(packageId, data, finished)

Return Type: void

Update the package expiration (days). Setting the life to 0 means the package will not expire.

Parameters:

Name	Type	Description
packageId	String	The packageId to update.
data	int	Json object containing a life parameter (integer). For example, {life:15}. int value must be a valid number between 0 and 365.
finished	function	function (PackageInformation)

Raised Events:

Event	Signature	Description
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

Adds a secure message to the package. If a message already exists it will be overwritten.

Parameters:

Name	Type	Description
packageId	String	The packageId that you are adding the message to.
keyCode	String	The keycode for the package.
serverSecret	String	The server secret associated with the package.
message	String	The message to be encrypted (text).
finished	function	function ()

Raised Events:

Event	Signature	Description
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

Adds a list of files to the package. Files will be encrypted and uploaded to the server and stored in the root directory of the package.

Parameters:

Name	Type	Description
packageId	String	The packageId that you are adding the file to.
keyCode	String	The key code associated with the package.
serverSecret	String	The server secret associated with the package.
files	List<file>	An array of files that are being uploaded.
uploadType	String	Optional Leave blank (or specify 'NODE_API').
finished	function	function (packageId, fileId, fileSize, fileName)

Raised Events:

Event	Signature	Description
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})

encryptAndUploadFilesToDirectory(packageId, keyCode, serverSecret, files, uploadType, directoryId, finished)

Return Type: void

Adds a list of files to the package within a specific directory . Files will be encrypted and uploaded to the server.

Parameters:

Name	Type	Description
packageId	String	The packageId that you are adding the file to.
keyCode	String	The key code associated with the package.
serverSecret	String	The server secret associated with the package.
files	List<file>	An array of files that are being uploaded.
uploadType	String	Optional Leave blank (or specify 'NODE_API').
directoryId	String	The directoryId of the directory that you want to add the files to.
finished	function	function (packageId, fileId, fileSize, fileName)

Raised Events:

Event	Signature	Description
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})

getKeycode(privateKey, publicKeyId, packageId, callback)

Return Type: void

Downloads and decrypts a keycode from the server for the given a packageId and Trusted Device key pair.

Parameters:

Name	Type	Description
privateKey	String	The private key portion of the Trusted Device key pair.
publicKeyId	String	The public key id associated with the Trusted Device key pair.
packageId	String	The package id you would like to obtain the keycode for.
callback	function	function (keycode)

Raised Events:

Event	Signature	Description
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

generateRsaKeyPair(description, callback)

Return Type: void

Generates a new Trusted Device key pair. The private key and public key returned. The public key is uploaded and stored on the SendSafely servers. The public key returned also includes an "id" parameter that used to uniquely identify the Trusted Device key.

Parameters:

Name	Type	Description
description	String	Field used to describe or name the key pair (ie My Node Script Key).
callback	function	function (privateKey, publicKey).

Raised Events:

Event	Signature	Description
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

removePublicKey(publicKeyId, callback)

Return Type: void

Revokes a Trusted Device key pair. Only call this function if the private key has been deleted and should never be used anymore (cannot be undone).

Parameters:

Name	Type	Description
publicKeyId	String	The public key id to revoke.
callback	function

Raised Events:

Event	Signature	Description
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 an individual file from the root directory of a package.

Parameters:

Name	Type	Description
packageId	String	The packageId of the package containing the file.
fileId	String	The fileId of the file to be downloaded.
keyCode	String	The keycode associated with the package.
config	Json	JSON configuration object required for file downloads over 2GB. To enable large file downloads, pass a JSON object with a path and/or fileName property. For example {path:'downloads', fileName:'example.txt'} results in the downloaded file being named "example.txt" to the "downloads" directory relative to the working directory. If the fileName property is omitted, the fileName returned from SendSafely will be used.

Raised Events:

Event	Signature	Description
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
file.saved	function({fileId: String, config: Json})	The raw decrypted file stream for large file downloads. Use this event to save the file to the actual file system using a write stream

downloadFileFromDirectory(packageId, directoryId, fileId, keyCode, config)

Return Type: void

Downloads and decrypts an individual file from a specific directory of the package.

Parameters:

Name	Type	Description
packageId	String	The packageId of the package containing the file.
directoryId	String	The directoryId of the directory containing the file.
fileId	String	The fileId of the file to be downloaded.
keyCode	String	The keycode associated with the package.
config	Json	JSON configuration object required for file downloads over 2GB. To enable large file downloads, pass a JSON object with a path and/or fileName property. For example {path:'downloads', fileName:'example.txt'} results in the downloaded file being named "example.txt" to the "downloads" directory relative to the working directory. If the fileName property is omitted, the fileName returned from SendSafely will be used.

Raised Events:

Event	Signature	Description
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
file.saved	function({fileId: String, config: Json})	The raw decrypted file stream for large file downloads. Use this event to save the file to the actual file system using a write stream

createDirectory(packageId, directoryName, finished)

Return Type: void

Creates a new directory in the root folder of a Workspace. Only Workspace packages support this function.

Parameters:

Name	Type	Description
packageId	String	The package id of the package.
directoryName	String	The name of the directory to be added to the workspace.
finished	function	function ()

Raised Events:

Event	Signature	Description
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

createSubdirectory(packageId, directoryName, directoryId, finished)

Return Type: void

Creates a new sub-directory in a Workspace. Only Workspace packages support this function.

Parameters:

Name	Type	Description
packageId	String	The package id of the package.
directoryName	String	The name of the directory to be added to the workspace.
directoryId	String	The directory id of parent directory in which to create this sub-directory. If creating a directory in the root directory of a Workspace, this will be the packageDirectoryId property of the Workspace Package.
finished	function	function ()

Raised Events:

Event	Signature	Description
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

updateDirectory(packageId, sourceDirectoryId, targetDirectoryId, finished)

Return Type: void

Moves a directory from its current location to the specified destination directory in a Workspace package.

Parameters:

Name	Type	Description
packageId	String	The package id of the package.
sourceDirectoryId	String	The directory id of the directory to move. The source directory and the target directory must belong to the same package.
targetDirectoryId	String	The directory id of the destination directory. The source directory and the target directory must belong to the same package.
finished	function	function ()

Raised Events:

Event	Signature	Description
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

hasOngoingUploads()

Return Type: boolean

Utility function to check if the package has any ongoing uploads.

Parameters: N/A

Raised Events: N/A

createPackage(finished)

Return Type: void

Create a new empty package.

Parameters:

Name	Type	Description
finished	function	function (packageId, serverSecret, packageCode, keyCode)

Raised Events:

Event	Signature	Description
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

createWorkspace(finished)

Return Type: void

Create a new empty Workspace package.

Parameters:

Name	Type	Description
finished	function	function (packageId, serverSecret, packageCode, keyCode)

Raised Events:

Event	Signature	Description
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

decryptMessage(packageId, keyCode, serverSecret, ciphertext, finished)

Return Type: void

Decrypt the message from a package.

Parameters:

Name	Type	Description
packageId	String	The packageId that contains the message to be decrypted.
keyCode	String	The keycode associated with the package.
serverSecret	String	The server secret associated with the package.
ciphertext	String	The ciphertext message to decrypt.
finished	function	function(decryptedMessage)

Raised Events:

Event	Signature	Description
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

Name	Type	Description
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

Name	Type	Description
recipientId	String	N/A
email	String	N/A
needsApproval	bool	N/A

File

Name	Type	Description
fileId	String	N/A
fileName	String	N/A
fileSize	Integer	N/A

PackageState

Name	Type	Description
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

JavaScript Client API Reference

SendSafely.js