cloudFile API

The cloudFile (a.k.a. fileLink) API allows to create a provider to store large attachments in the cloud instead of attaching them directly to the message.

Manifest file properties

cloud_file

[cloud_file]

(object, optional)

– [Added in TB 64]

management_url

management_url

(string)

– [Added in TB 64]

A page for configuring accounts, to be displayed in the preferences UI.

Note

Within this UI only a limited subset of the WebExtension APIs is available: cloudFile, extension, i18n, runtime, storage. The id of the to be configured cloud file account can be retrieved via new URL(location.href).searchParams.get(‘accountId’);.

name

name

(string)

– [Added in TB 64]

Name of the cloud file service.

browser_style

[browser_style]

(boolean, optional)

– [Added in TB 90]

Enable browser styles in the management_url page. See the MDN documentation on browser styles for more information.

data_format

[data_format]

(string, optional) Deprecated.

– [Added in TB 71]

This property is no longer used. The only supported data format for the data argument in onFileUpload is File.

new_account_url

[new_account_url]

(string, optional) Deprecated.

– [Added in TB 64]

This property was never used.

reuse_uploads

[reuse_uploads]

(boolean, optional)

– [Added in TB 98]

If a previously uploaded cloud file attachment is reused at a later time in a different message, Thunderbird may use the already known url and templateInfo values without triggering the registered onFileUpload listener again. Setting this option to false will always trigger the registered listener, providing the already known values through the relatedFileInfo parameter of the onFileUpload event, to let the provider decide how to handle these cases.

service_url

[service_url]

(string, optional) Deprecated.

– [Added in TB 64]

This property is no longer used. The service_url property of the CloudFileTemplateInfo object returned by the onFileUpload event can be used to add a Learn more about link to the footer of the cloud file attachment element.

Permissions

Note

A manifest entry named cloud_file is required to use messenger.cloudFile.*.

Functions

getAccount(accountId)

– [Added in TB 64]

Retrieve information about a single cloud file account. Returns undefined, if the requested account does not exist.

Parameters

accountId

accountId

(string)

Unique identifier of the account.

Return type (Promise)

_returns

– [Added in TB 89]

getAllAccounts()

– [Added in TB 64]

Retrieve all cloud file accounts for the current add-on.

Return type (Promise)

_returns

array of CloudFileAccount

– [Added in TB 89]

updateAccount(accountId, updateProperties)

– [Added in TB 64]

Update a cloud file account. Returns undefined, if the requested account does not exist.

Parameters

accountId

accountId

(string)

Unique identifier of the account.

updateProperties

updateProperties

(object)

configured

[configured]

(boolean, optional)

If true, the account is configured and ready to use. Only configured accounts are offered to the user.

managementUrl

[managementUrl]

(string, optional)

A page for configuring accounts, to be displayed in the preferences UI.

spaceRemaining

[spaceRemaining]

(integer, optional)

The amount of remaining space on the cloud provider, in bytes. Set to -1 if unsupported.

spaceUsed

[spaceUsed]

(integer, optional)

The amount of space already used on the cloud provider, in bytes. Set to -1 if unsupported.

uploadSizeLimit

[uploadSizeLimit]

(integer, optional)

The maximum size in bytes for a single file to upload. Set to -1 if unlimited.

Return type (Promise)

_returns

– [Added in TB 89]

Events

onAccountAdded

– [Added in TB 64]

Fired when a cloud file account of this add-on was created.

Parameters for onAccountAdded.addListener(listener)

listener(account)

listener(account)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

account

The created account.

onAccountDeleted

– [Added in TB 64]

Fired when a cloud file account of this add-on was deleted.

Parameters for onAccountDeleted.addListener(listener)

listener(accountId)

listener(accountId)

A function that will be called when this event occurs.

Parameters passed to the listener function

accountId

accountId

(string)

The id of the removed account.

onFileDeleted

– [Added in TB 64]

Fired when a previously uploaded file should be deleted.

Parameters for onFileDeleted.addListener(listener)

listener(account, fileId, tab)

listener(account, fileId, tab)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

account

The account used for the file upload.

fileId

fileId

(integer)

An identifier for this file.

tab

tab

(Tab)

– [Added in TB 91]

The tab where the upload was initiated. Currently only available for the message composer.

onFileRename

– [Added in TB 97]

Fired when a previously uploaded file should be renamed.

Parameters for onFileRename.addListener(listener)

listener(account, fileId, newName, tab)

listener(account, fileId, newName, tab)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

account

The account used for the file upload.

fileId

fileId

(integer)

An identifier for the file which should be renamed.

newName

newName

(string)

The new name of the file.

tab

tab

(Tab)

The tab where the rename was initiated. Currently only available for the message composer.

Expected return value of the listener function

cloud-file-on-file-rename-returns

object

error

[error]

(boolean or string, optional)

Report an error to the user. Set this to true for showing a generic error message, or set a specific error message.

url

[url]

(string, optional)

The URL where the renamed file can be accessed.

onFileUpload

– [Added in TB 64]

Fired when a file should be uploaded to the cloud file provider.

Parameters for onFileUpload.addListener(listener)

listener(account, fileInfo, tab, relatedFileInfo)

listener(account, fileInfo, tab, relatedFileInfo)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

account

The account used for the file upload.

fileInfo

fileInfo

The file to upload.

tab

tab

(Tab)

– [Added in TB 91]

The tab where the upload was initiated. Currently only available for the message composer.

relatedFileInfo

[relatedFileInfo]

(RelatedCloudFile, optional)

– [Added in TB 98]

Information about an already uploaded file, which is related to this upload.

Expected return value of the listener function

cloud-file-on-file-upload-returns

object

aborted

[aborted]

(boolean, optional)

Set this to true if the file upload was aborted by the user and an onFileUploadAbort event has been received. No error message will be shown to the user.

error

[error]

(boolean or string, optional)

– [Added in TB 97]

Report an error to the user. Set this to true for showing a generic error message, or set a specific error message.

templateInfo

[templateInfo]

(CloudFileTemplateInfo, optional)

– [Added in TB 96]

Additional file information used in the cloud file entry added to the message.

url

[url]

(string, optional)

The URL where the uploaded file can be accessed.

onFileUploadAbort

– [Added in TB 64]

Parameters for onFileUploadAbort.addListener(listener)

listener(account, fileId, tab)

listener(account, fileId, tab)

A function that will be called when this event occurs.

Parameters passed to the listener function

account

account

The account used for the file upload.

fileId

fileId

(integer)

An identifier for this file.

tab

tab

(Tab)

– [Added in TB 91]

The tab where the upload was initiated. Currently only available for the message composer.

Types

CloudFile

– [Added in TB 64]

Information about a cloud file.

object

data

data

(File)

Contents of the file to be transferred.

id

id

(integer)

An identifier for this file.

name

name

(string)

Filename of the file to be transferred.

CloudFileAccount

– [Added in TB 64]

Information about a cloud file account.

object

configured

configured

(boolean)

If true, the account is configured and ready to use. Only configured accounts are offered to the user.

id

id

(string)

Unique identifier of the account.

managementUrl

managementUrl

(string)

A page for configuring accounts, to be displayed in the preferences UI.

name

name

(string)

A user-friendly name for this account.

spaceRemaining

[spaceRemaining]

(integer, optional)

The amount of remaining space on the cloud provider, in bytes. Set to -1 if unsupported.

spaceUsed

[spaceUsed]

(integer, optional)

The amount of space already used on the cloud provider, in bytes. Set to -1 if unsupported.

uploadSizeLimit

[uploadSizeLimit]

(integer, optional)

The maximum size in bytes for a single file to upload. Set to -1 if unlimited.

CloudFileTemplateInfo

– [Added in TB 96]

Defines information to be used in the cloud file entry added to the message.

object

download_expiry_date

[download_expiry_date]

(object, optional)

– [Added in TB 97]

If set, the cloud file entry for this upload will include a hint, that the link will only be available for a limited time.

timestamp

timestamp

(integer)

– [Added in TB 97]

The expiry date of the link as the number of milliseconds since the UNIX epoch.

format

[format]

(object, optional)

– [Added in TB 97]

A format options object as used by Intl.DateTimeFormat.

Defaults to:

{
  "day": "2-digit",
  "month": "2-digit",
  "year": "numeric",
  "hour": "2-digit",
  "minute": "2-digit",
  "timeZoneName": "short"
}

download_limit

[download_limit]

(integer, optional)

– [Added in TB 97]

If set, the cloud file entry for this upload will include a hint, that the file has a download limit.

download_password_protected

[download_password_protected]

(boolean, optional)

– [Added in TB 97]

If set to true, the cloud file entry for this upload will include a hint, that the download link is password protected.

service_icon

[service_icon]

(string, optional)

A URL pointing to an icon to represent the used cloud file service. Defaults to the icon of the provider add-on.

service_name

[service_name]

(string, optional)

A name to represent the used cloud file service. Defaults to the associated cloud file account name.

service_url

[service_url]

(string, optional)

A URL pointing to a web page of the used cloud file service. Will be used in a Learn more about link in the footer of the cloud file attachment element.

RelatedCloudFile

– [Added in TB 98]

Information about an already uploaded cloud file, which is related to a new upload. For example if the content of a cloud attachment is updated, if a repeatedly used cloud attachment is renamed (and therefore should be re-uploaded to not invalidate existing links) or if the provider has its manifest property reuse_uploads set to false.

object

dataChanged

dataChanged

(boolean)

The content of the new upload differs from the related file.

name

name

(string)

Filename of the related file.

id

[id]

(integer, optional)

The identifier for the related file. In some circumstances, the id is unavailable.

templateInfo

[templateInfo]

(CloudFileTemplateInfo, optional)

Additional information of the related file, used in the cloud file entry added to the message.

url

[url]

(string, optional)

The URL where the upload of the related file can be accessed.