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¶
Move, copy, or delete your email messages
Read your email messages and mark or tag them
Functions¶
list(folder)¶
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.
Parameters
messageId
(integer)
Return type (Promise)
Required permissions
getRaw(messageId)¶
– [Added in TB 68.7]
Returns the unmodified source of a message.
Parameters
messageId
(integer)
Return type (Promise)
string
Required permissions
query(queryInfo)¶
– [Added in 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.
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 matching any configured identity.
[fullText]
(string)
Returns only messages with this value somewhere in the mail (subject, body or author).
[recipients]
(string)
Returns only messages with this value matching one or more recipients.
[subject]
(string)
Returns only messages with this value matching the subject.
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)
Required permissions
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 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
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, 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
archive(messageIds)¶
Archives messages using the current settings.
Parameters
messageIds
(array of integer)
The IDs of the messages to archive.
Required permissions
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
Types¶
MessageHeader¶
object
author
(string)
bccList
(array of string)
ccList
(array of string)
date
(date)
flagged
(boolean)
The permission is required.
id
(integer)
read
(boolean)
recipients
(array of string)
subject
(string)
tags
(array of string)
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)
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)
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