messages API
The messages API first appeared in Thunderbird 66.
Note
When the term messageId is used in these documents, it doesn’t refer to the Message-ID
email header. It is an internal tracking number that does not remain after a restart. Nor does
it follow an email that has been moved to a different folder.
Warning
Some functions in this API potentially return a lot of messages. Be careful what you wish for! See Working with message lists for more information.
Permissions
Copy or move your email messages (including moving them to the trash folder)
Read your email messages and mark or tag them
Permanently delete your email messages
Create, modify and delete message tags
Functions
list(folder)
Gets all messages in a folder.
Parameters
Return type (Promise)
Required permissions
continueList(messageListId)
Returns the next chunk of messages in a list. See Working with message lists for more information.
Parameters
messageListId
(string)
Return type (Promise)
Required permissions
get(messageId)
Returns a specified message.
Parameters
messageId
(integer)
Return type (Promise)
Required permissions
getFull(messageId)
Returns a specified message, including all headers and MIME parts. Throws if the message could not be read, for example due to network issues.
Parameters
messageId
(integer)
Return type (Promise)
Required permissions
getRaw(messageId)
– [Added in TB 72, backported to TB 68.7]
Returns the unmodified source of a message as a binary string, which is a simple series of 8-bit values. Throws if the message could not be read, for example due to network issues. If the message contains non-ASCII characters, the body parts in the binary string cannot be read directly and must be decoded according to their character sets. Use getFull(messageId) to get the correctly decoded parts. Manually decoding the raw message is probably too error-prone, especially if the message contains MIME parts with different character set encodings or attachments.
To get a readable version of the raw message as it appears in Thunderbird’s message source view, it may be sufficient to decode the message according to the character set specified in its main content-type header (example: text/html; charset=UTF-8) using the following function (see MDN for supported input encodings):
/**
* Decodes a binary string using the given encoding format and returns a
* JavaScript string. Produces mangled output if used with anything but a binary
* input string.
*/
function decodeBinaryString(binaryString, inputEncoding = "utf-8") {
const buffer = new Uint8Array(binaryString.length);
for (let i = 0; i < binaryString.length; i++) {
buffer[i] = binaryString.charCodeAt(i) & 0xFF;
}
let decoder = new TextDecoder(inputEncoding);
return decoder.decode(buffer);
}
Parameters
messageId
(integer)
Return type (Promise)
string
Required permissions
listAttachments(messageId)
– [Added in TB 88]
Lists the attachments of a message.
Parameters
messageId
(integer)
Return type (Promise)
array of MessageAttachment
Required permissions
getAttachmentFile(messageId, partName)
– [Added in TB 88]
Gets the content of a MessageAttachment as a File object.
Parameters
messageId
(integer)
partName
(string)
Required permissions
The most simple way to get the content of an attachment is to use the text() method of the returned File object:
let attachments = await browser.messages.listAttachments(messageId);
for (let att of attachments) {
let file = await browser.messages.getAttachmentFile(
messageId,
att.partName
);
let content = await file.text();
}
query(queryInfo)
– [Added in TB 69, backported to TB 68.2]
Gets all messages that have the specified properties, or all messages if no properties are specified.
Parameters
queryInfo
(object)
[attachment]
(boolean)
– [Added in TB 96, backported to TB 91.4.1]
If specified, returns only messages with or without attachments.
[author]
(string)
Returns only messages with this value matching the author. The search value is a single email address, a name or a combination (e.g.: Name <user@domain.org>). The address part of the search value (if provided) must match the author’s address completely. The name part of the search value (if provided) must match the author’s name partially. All matches are done case-insensitive.
[body]
(string)
Returns only messages with this value in the body of the mail.
[flagged]
(boolean)
Returns only flagged (or unflagged if false) messages.
Returns only messages from the specified folder. The permission is required.
Returns only messages with a date after this value.
[fromMe]
(boolean)
Returns only messages with the author’s address matching any configured identity.
[fullText]
(string)
Returns only messages with this value somewhere in the mail (subject, body or author).
[headerMessageId]
(string)
– [Added in TB 85]
Returns only messages with a Message-ID header matching this value.
[includeSubFolders]
(boolean)
– [Added in TB 91]
Search the folder specified by queryInfo.folder recursively.
[recipients]
(string)
Returns only messages whose recipients match all specified addresses. The search value is a semicolon separated list of email addresses, names or combinations (e.g.: Name <user@domain.org>). For a match, all specified addresses must equal a recipient’s address completely and all specified names must match a recipient’s name partially. All matches are done case-insensitive.
[subject]
(string)
Returns only messages with this value matching the subject.
Returns only messages with the specified tags. For a list of available tags, call the listTags() method.
Returns only messages with a date before this value.
[toMe]
(boolean)
Returns only messages with at least one recipient address matching any configured identity.
[unread]
(boolean)
Returns only unread (or read if false) messages.
Return type (Promise)
Required permissions
update(messageId, newProperties)
Marks or unmarks a message as junk, read, flagged, or tagged.
Required permissions
move(messageIds, destination)
Moves messages to a specified folder.
Parameters
messageIds
(array of integer)
The IDs of the messages to move.
The folder to move the messages to.
Required permissions
copy(messageIds, destination)
Copies messages to a specified folder.
Parameters
messageIds
(array of integer)
The IDs of the messages to copy.
The folder to copy the messages to.
Required permissions
delete(messageIds, [skipTrash])
Deletes messages permanently, or moves them to the trash folder (honoring the account’s deletion behavior settings). The skipTrash parameter allows immediate permanent deletion, bypassing the trash folder.
Note: Consider using move(messageIds, destination) to manually move messages to the account’s trash folder, instead of requesting the overly powerful permission to actually delete messages. The account’s trash folder can be extracted as follows:
/**
* Returns the trash folder of the account a given message belongs to. The
* accountsRead permission is required.
*/
async function getTrashFolderForMessage(msgId) {
let msg = await messenger.messages.get(msgId);
let account = await messenger.accounts.get(msg.folder.accountId);
return account.folders.find(folder => folder.type == "trash");
}
Parameters
messageIds
(array of integer)
The IDs of the messages to delete.
[skipTrash]
(boolean)
If true, the message will be deleted permanently, regardless of the account’s deletion behavior settings.
Required permissions
archive(messageIds)
Archives messages using the current settings.
Parameters
messageIds
(array of integer)
The IDs of the messages to archive.
Required permissions
Returns a list of tags that can be set on messages, and their human-friendly name, colour, and sort order.
Return type (Promise)
array of MessageTag
Required permissions
createTag(key, tag, color)
– [Added in TB 102]
Creates a new message tag. Tagging a message will store the tag’s key in the user’s message. Throws if the specified tag key is used already.
Parameters
key
(string)
Unique tag identifier (must use only alphanumeric characters).
tag
(string)
Human-readable tag name.
color
(string)
Tag color in hex format (i.e.: #000080 for navy blue)
Required permissions
updateTag(key, updateProperties)
– [Added in TB 102]
Updates a message tag.
Parameters
key
(string)
Unique tag identifier.
updateProperties
(object)
[color]
(string)
Tag color in hex format (i.e.: #000080 for navy blue).
[tag]
(string)
Human-readable tag name.
Required permissions
deleteTag(key)
– [Added in TB 102]
Deletes a message tag, removing it from the list of known tags. Its key will not be removed from tagged messages, but they will appear untagged. Recreating a deleted tag, will make all former tagged messages appear tagged again.
Parameters
key
(string)
Required permissions
Events
onUpdated
– [Added in TB 91]
Fired when one or more properties of a message have been updated.
Parameters for onUpdated.addListener(listener)
listener(message, changedProperties)
A function that will be called when this event occurs.
Parameters passed to the listener function
Required permissions
onMoved
– [Added in TB 91]
Fired when messages have been moved.
Parameters for onMoved.addListener(listener)
listener(originalMessages, movedMessages)
A function that will be called when this event occurs.
Parameters passed to the listener function
Required permissions
onCopied
– [Added in TB 91]
Fired when messages have been copied.
Parameters for onCopied.addListener(listener)
listener(originalMessages, copiedMessages)
A function that will be called when this event occurs.
Parameters passed to the listener function
Required permissions
onDeleted
– [Added in TB 91]
Fired when messages have been permanently deleted.
Parameters for onDeleted.addListener(listener)
listener(messages)
A function that will be called when this event occurs.
Parameters passed to the listener function
Required permissions
onNewMailReceived
– [Added in TB 75]
Fired when a new message is received, and has been through junk classification and message filters.
Parameters for onNewMailReceived.addListener(listener)
listener(folder, messages)
A function that will be called when this event occurs.
Required permissions
Types
MessageAttachment
Represents an attachment in a message.
object
contentType
(string)
The content type of the attachment.
name
(string)
The name, as displayed to the user, of this attachment. This is usually but not always the filename of the attached file.
partName
(string)
Identifies the MIME part of the message associated with this attachment.
size
(integer)
The size in bytes of this attachment.
MessageChangeProperties
Message properties that can be updated by the update(messageId, newProperties) and that are monitored by onUpdated.
object
[flagged]
(boolean)
Message is flagged.
[junk]
(boolean)
Message is junk.
[read]
(boolean)
Message is read.
[tags]
(array of string)
Tags associated with this message. For a list of available tags, call the listTags method.
MessageHeader
Basic information about a message.
object
author
(string)
bccList
(array of string)
The Bcc recipients. Not populated for news/nntp messages.
ccList
(array of string)
The Cc recipients. Not populated for news/nntp messages.
flagged
(boolean)
headerMessageId
(string)
– [Added in TB 85]
The message-id header of the message.
headersOnly
(boolean)
– [Added in TB 102]
Some account types (for example pop3) allow to download only the headers of the message, but not its body. The body of such messages will not be available.
id
(integer)
junk
(boolean)
– [Added in TB 74]
Not populated for news/nntp messages.
junkScore
(integer)
– [Added in TB 74]
read
(boolean)
recipients
(array of string)
The To recipients. Not populated for news/nntp messages.
size
(integer)
– [Added in TB 90]
The total size of the message in bytes.
subject
(string)
The subject of the message.
tags
(array of string)
Tags associated with this message. For a list of available tags, call the listTags method.
The permission is required for this property to be included.
MessageList
See Working with message lists for more information.
MessagePart
Represents an email message “part”, which could be the whole message
object
[body]
(string)
The content of the part
[contentType]
(string)
[headers]
(object)
A dictionary object of part headers as key-value pairs, with the header name as key, and an array of headers as value
[name]
(string)
Name of the part, if it is a file
[partName]
(string)
The identifier of this part, used in getAttachmentFile(messageId, partName)
Any sub-parts of this part
[size]
(integer)
The size of this part. The size of message/* parts is not the actual message size (on disc), but the total size of its decoded body parts, excluding headers.
MessageTag
object
color
(string)
Tag color.
key
(string)
Unique tag identifier.
ordinal
(string)
Custom sort string (usually empty).
tag
(string)
Human-readable tag name.
Used for filtering messages by tag in various methods. Note that functions using this type may have a partial implementation.
object
mode
(string)
Whether all of the tag filters must apply, or any of them.
Supported values:
all
any
tags
(object)
A dictionary object with one or more filter condition as key-value pairs, the key being the tag to filter on, and the value being a boolean expression, requesting whether a message must include (true) or exclude (false) the tag. For a list of available tags, call the listTags() method.