messages

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

messagesMove
Move, copy, or delete your email messages
messagesRead
Read your email messages and mark or tag them

Note

The permission messagesRead is required to use messages.

Functions

list(folder)

Gets all messages in a folder.

Parameters
folder
(MailFolder)
Return type (Promise)
MessageList
Required permissions
  • messagesRead
  • accountsRead

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)
MessageList
Required permissions
  • messagesRead

get(messageId)

Returns a specified message.

Parameters
messageId
(integer)
Return type (Promise)
MessageHeader
Required permissions
  • messagesRead

getFull(messageId)

Returns a specified message, including all headers and MIME parts.

Parameters
messageId
(integer)
Return type (Promise)
MessagePart
Required permissions
  • messagesRead

getRaw(messageId)

– [Added in TB 72, backported to TB 68.7]

Returns the unmodified source of a message as a binary string.

Parameters
messageId
(integer)
Return type (Promise)
string
Required permissions
  • messagesRead

listAttachments(messageId)

– [Added in TB 88]

Lists all of the attachments of a message.

Parameters
messageId
(integer)
Return type (Promise)
array of Attachment
Required permissions
  • messagesRead

getAttachmentFile(messageId, partName)

– [Added in TB 88]

Gets the content of an attachment as a DOM File object.

Parameters
messageId
(integer)
partName
(string)
Return type (Promise)
File
Required permissions
  • messagesRead

The most simple way to get the content of an attachment is to use the text() method of the 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)
[author]
(string)
Returns only messages with this value matching the author.
[body]
(string)
Returns only messages with this value in the body of the mail.
[flagged]
(boolean)
Returns only flagged (or unflagged if false) messages.
[folder]
(MailFolder)
Returns only messages from the specified folder. The accountsRead permission is required.
[fromDate]
(Date)
Returns only messages with a date after this value.
[fromMe]
(boolean)
Returns only messages with the author 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.
[recipients]
(string)
Returns only messages with this value matching one or more recipients.
[subject]
(string)
Returns only messages with this value matching the subject.
[tags]
(TagsDetail)
– [Added in TB 74]
Returns only messages with the specified tags. For a list of available tags, call the listTags method. Querying for messages that must not have a tag does not work.
[toDate]
(Date)
Returns only messages with a date before this value.
[toMe]
(boolean)
Returns only messages with one or more recipients matching any configured identity.
[unread]
(boolean)
Returns only unread (or read if false) messages.
Return type (Promise)
MessageList
Required permissions
  • messagesRead

update(messageId, newProperties)

Marks or unmarks a message as read, flagged, or tagged.

Parameters
messageId
(integer)
newProperties
(object)
[flagged]
(boolean)
Marks the message as flagged or unflagged.
[junk]
(boolean)
– [Added in TB 73, backported to TB 68.7]
Marks the message as junk or not junk.
[read]
(boolean)
Marks the message as read or unread.
[tags]
(array of string)
Sets the tags on the message. For a list of available tags, call the listTags method.
Required permissions
  • messagesRead

move(messageIds, destination)

Moves messages to a specified folder.

Parameters
messageIds
(array of integer)
The IDs of the messages to move.
destination
(MailFolder)
The folder to move the messages to.
Required permissions
  • messagesRead
  • accountsRead
  • messagesMove

copy(messageIds, destination)

Copies messages to a specified folder.

Parameters
messageIds
(array of integer)
The IDs of the messages to copy.
destination
(MailFolder)
The folder to copy the messages to.
Required permissions
  • messagesRead
  • accountsRead
  • messagesMove

delete(messageIds, [skipTrash])

Deletes messages, or moves them to the trash folder.

Parameters
messageIds
(array of integer)
The IDs of the messages to delete.
[skipTrash]
(boolean)
If true, the message will be permanently deleted without warning the user. If false or not specified, it will be moved to the trash folder.
Required permissions
  • messagesRead
  • messagesMove

archive(messageIds)

Archives messages using the current settings.

Parameters
messageIds
(array of integer)
The IDs of the messages to archive.
Required permissions
  • messagesRead
  • messagesMove

listTags()

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
  • messagesRead

Events

onNewMailReceived(folder, messages)

– [Added in TB 75]

Fired when a new message is received, and has been through junk classification and message filters.

Parameters for event listeners
folder
(MailFolder)
messages
(MessageList)
Required permissions
  • messagesRead
  • accountsRead

Types

Attachment

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.

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.
date
(Date)
flagged
(boolean)
folder
(MailFolder)
The accountsRead permission is required for this property to be included.
headerMessageId
(string)
– [Added in TB 85]
The message-id header of the message.
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)
tags
(array of string)

MessageList

See Working with Message Lists for more information.

object
messages
(array of MessageHeader)
[id]
(string)

MessagePart

Represents an email message “part”, which could be the whole message

object
[body]
(string)
The content of the part
[contentType]
(string)
[headers]
(object)
An object of part headers, with the header name as key, and an array of header values as value
[name]
(string)
Name of the part, if it is a file
[partName]
(string)
[parts]
(array of MessagePart)
Any sub-parts of this part
[size]
(integer)

MessageTag

object
color
(string)
Tag color
key
(string)
Distinct tag identifier – use this string when referring to a tag
ordinal
(string)
Custom sort string (usually empty)
tag
(string)
Human-readable tag name

TagsDetail

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)
Object keys are tags to filter on, values are true if the message must have the tag, or false if it must not have the tag. For a list of available tags, call the listTags() method.