Conversations
This namespace allows you to interact with Gmail conversations (typically called threads). The fundamental views you interact with are ThreadView and MessageView and there is a 1 to many relationship between them. The functions in Conversations.* allow you to obtain these views which you can then further manipulate.
It's important to note that ThreadViews and MessageViews can be navigated to in various ways by the user depending on their email client and their settings (i.e. preview pane on in Gmail). This is abstracted completely away from you so you can just focus on manipulating the views once they are given to you.
Finally, when a ThreadView loads, you're not guranteed that every MessageView in it is also loaded. When you call ThreadView.getMessageViews it will return all MessageViews, but its important to remember that the MessageViews might not be loaded. MessageViews can be in several states. Consult the MessageView documentation to learn about what functionality is available in each state.
Namespace methods
registerThreadViewHandler(handler)
Registers your handler to be called when the user navigates to a ThreadView. Your handler is given a ThreadView which you can then further manipulate.
| Parameters | Type | Description |
|---|---|---|
| handler | function(ThreadView) | The handler to call when a ThreadView is displayed. This handler is passed one parameter, a ThreadView. |
Returns a function which removes the handler registration.
registerMessageViewHandler(handler)
Registers your handler to be called when a MessageView is displayed. Your handler is given a MessageView which you can then further manipulate.
IMPORTANT: Your handler will only be called for MessageViews that are "loaded". See docs for MessageView to understand the distinction.
| Parameters | Type | Description |
|---|---|---|
| handler | function(MessageView) | The handler to call when a MessageView is displayed. |
Returns a function which removes the handler registration.
registerMessageViewHandlerAll(handler)
Registers your handler to be called when the user navigates to a MessageView. Your handler is given a MessageView which you can then further manipulate.
IMPORTANT: Your handler will be called for MessageViews that are both "loaded" and "unloaded". See docs for MessageView to understand the distinction.
| Parameters | Type | Description |
|---|---|---|
| handler | function(MessageView) | The handler to call when a message view is displayed. |
Returns a function which removes the handler registration.
registerFileAttachmentCardViewHandler(handler)
Registers your handler to be called when an AttachmentCardView is visible.
| Parameters | Type | Description |
|---|---|---|
| handler | function(ComposeView) | The handler to call when am attachment card view is displayed. |
Returns a function which removes the handler registration.
ThreadView
Object that represents a visible thread view that the user has navigated to
Methods
addNoticeBar()
Inserts a "notice bar" element below the thread subject. The element defaults to having a yellow background color and specific padding to make it look like a warning on the thread, but your code may override these styles of the element.
Returns a SimpleElementView
addLabel()
Inserts a "label" element alongside the thread subject and all native labels. The element has no default styling. Adding your own is recommended.
Returns a SimpleElementView
addSidebarContentPanel(contentPanelDescriptor)
Inserts a content panel into the sidebar of a thread view. A content panel simply displays your content to the user, typically in the form of a sidebar. ThreadViews can have multiple content panels added to them and the SDK will handle creating a tabbed interface if needed.
| Parameters | Type | Description |
|---|---|---|
| contentPanelDescriptor | ContentPanelDescriptor | The details of the content panel to add to the thread's sidebar. |
Returns a ContentPanelView
getMessageViews()
Returns an Array<MessageView> of all the loaded MessageView objects currently in the thread. See MessageView for more information on what "loaded" means. Note that more messages may load into the thread later! If it's important to get future messages, use Conversations.registerMessageViewHandler instead.
getMessageViewsAll()
Returns an Array<MessageView> of all the MessageView objects in the thread regardless of their load state. See MessageView for more information on what "loaded" means.
getSubject()
Returns a string of the subject of this thread.
getThreadIDAsync()
Returns a Promise<string> of the Gmail Thread ID of the thread
Events
contactHover
Fires when the user hovers over a contact on any message in the thread ContactHoverEvent.
| Event properties | Type | Description |
|---|---|---|
| contact | Contact | the contact that was hovered over |
| contactType | string | whether the hovered contact was a 'sender' or 'recipient' |
| messageView | MessageView | the message view that the contact was a part of |
| threadView | ThreadView | the thread view that the contact was a part of |
destroy
Fires when the thread view is no longer visible (i.e. the user navigates away from the thread).
Properties
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| destroyed | boolean | This property is set to true once the view is destroyed. | Yes |
MessageView
Object that represents a visible message in the UI. There are properties to access data about the message itself as well as change the state of the UI. MessageViews have a view state as well as a loaded state. These 2 properties are orthogonal to each other.
A messages' view state can be one of MessageViewViewStates.EXPANDED, MessageViewViewStates.COLLAPSED or MessageViewViewStates.HIDDEN. Gmail visually display messages in a thread in different ways depending on what they are trying to show a user. These values are described in the enum MessageViewViewStates. The load state of a message determines whether all of the data pertaining to a message has been loaded in the UI. In some case, not all the information (such as recipients or the body) may be loaded, typically when the the view state is COLLAPSED or HIDDEN. You should not depend on any relationship between the view state and load state. Instead, use the provided MessageView.getViewState() and MessageView.isLoaded() methods.
Methods
addAttachmentCardView(cardOptions)
Adds an AttachmentCardView to the message. Each message has an area where attachments of that message are shown as a set of preview cards. These may be for file attachments or even inline YouTube links. This method allows you to add your own.
| Parameters | Type | Description |
|---|---|---|
| cardOptions | AttachmentCardOptions or AttachmentCardNoPreviewOptions | The configuration of the AttachmentCardView to create. |
Returns an AttachmentCardView
addAttachmentsToolbarButton(buttonOptions)
Adds a button to the download all area of the attachments tray.
| Parameters | Type | Description |
|---|---|---|
| buttonOptions | AttachmentsToolbarButtonDescriptor | The configuration of the button to create. |
addToolbarButton(options)
Adds a button to the message.
| Parameters | Type | Description |
|---|---|---|
| options | MessageViewToolbarButtonDescriptor | The configuration of the button to create. |
getBodyElement()
Returns the body element of the message as displayed to the user. This element includes any qouted areas. Use this method when you want to decorate the body of the message, i.e. if you wanted to linkify all dates you found in a message for scheduling purposes
Returns a HTMLElement
getMessageIDAsync()
Gets the ID of the message and returns it as a Promise. The promise will reject with an error if this is called on a message that isn't loaded yet.
Returns a Promise<string>
getFileAttachmentCardViews()
Returns all the attachment card views of type FILE currently visible for this message.
Returns an Array<AttachmentCardView>
isElementInQuotedArea()
Returns whether the element you provided or not is contained within the qouted area of the MessageView. This is useful when you want to parse through the contents of the HTMLElement returned by MessageView.getBodyElement() and test whether one if its children is in the qouted area (because you'll usually ignore those elements).
Returns a boolean
isLoaded()
Returns whether this message has been loaded yet. If the message has not been loaded, some of the data related methods on this object may return empty results. The message may be loaded once the user clicks on the message stub.
Returns a boolean
getLinksInBody()
Returns an array of MessageViewLinkDescriptors representing all the links in the message and their associated metadata. This is useful when you want to parse links in a message and take some action on them, this takes care of detecting whether the link is in the qouted area or not and parsing out the url/anchor text of the link. i.e. if you wanted to linkify all dates you found in a message for scheduling purposes
Returns an Array<MessageViewLinkDescriptor>
getSender()
Get the contact of the sender of this message.
Returns a Contact
getRecipientEmailAddresses()
Get all the recipient email addresses of this message (to, cc, bcc). This only reads the values directly present in the page, which may be truncated if there are many items. The asynchronous method getRecipientsFull() should be used instead if the full list is desired.
Returns an Array<string>
getRecipientsFull()
Get all the recipients of this message (to, cc, bcc). Returns a promise for an array of contact objects.
Returns a Array<Contact>
getThreadView()
Get the ThreadView that this MessageView is in.
Returns a ThreadView
getDateString()
Gets Gmail's representation of the timestamp of the message. Note: this returns a string representation because timezone information is not available, the accuracy is limited to minutes, and it is formatted to the user's language.
Returns a string
addAttachmentIcon(iconDescriptor)
Adds an attachment message's top line near the date. It returns an instance of AttachmentIcon which can subsribe to events 'tooltipShown' and 'tooltipHidden'.
| Parameters | Type | Description |
|---|---|---|
| iconDescriptor | MessageAttachmentIconDescriptor or Stream(MessageAttachmentIconDescriptor) | The options for the icon to add. |
Returns an AttachmentIcon
getViewState()
Returns the view state of this Message view. The possible view states are MessageViewViewStates.HIDDEN (no information visible), MessageViewViewStates.COLLAPSED (partial information visible) or MessageViewViewStates.EXPANDED
Returns a MessageViewViewStates
Events
viewStateChange
Fires when message viewState is changed
| Event properties | Type | Description |
|---|---|---|
| newViewState | MessageViewViewStates | the new state the message view is in |
| oldViewState | MessageViewViewStates | the old state the message view was in |
| messageView | MessageView | the message view whose state changed |
contactHover
Fires when the user hovers over a contact.
| Event properties | Type | Description |
|---|---|---|
| contact | Contact | the contact that was hovered over |
| contactType | string | whether the hovered contact was a 'sender' or 'recipient' |
| messageView | MessageView | the message view that the contact was a part of |
| threadView | ThreadView | the thread view that the contact was a part of |
load
Fires when the data for a message is loaded. This can happen when the message view is first presented or later when the user chooses to expand its view state.
destroy
Fires when the view card is destroyed
Properties
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| destroyed | boolean | This property is set to true once the view is destroyed. | Yes |
ContentPanelView
A view representing a panel of your apps content. This is the object that is returned when you add a sidebar content panel to a thread view or similar.
Methods
isActive()
Returns a boolean whether the content panel is currently visible.
open()
Makes the content panel visible, opening the sidebar if necessary.
remove()
Removes the content panel from its host.
Events
activate
Fires when the content panel becomes visisble. This can happen the first time the Panel is shown or subsequent times if the panel is presented in a tabbed interface and the ContentPanels tab is selected.
deactivate
Fires when the content panel is hidden. Typically this occurs when the user switches to another ContentPanel.
destroy
Fires when the content panel view is no longer valid (i.e. the user navigates away from the thread with the sidebar).
Properties
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| destroyed | boolean | This property is set to true once the view is destroyed. | Yes |
AttachmentCardView
Object that represents an Attachment Card visible in a message containing attachments.
Methods
getAttachmentType()
Returns the type of the attachment card. Values returned include FILE (regular file attachments), DRIVE (Drive attachments that are present as links in the message), CUSTOM (attachment cards added by this or other apps built on the SDK), and UNKNOWN (for other types of attachment cards rendered by Gmail that aren't specifically supported currently such as YouTube and Yelp links).
Returns a string
addButton(buttonDescriptor)
Adds a button to this attachment card.
| Parameters | Type | Description |
|---|---|---|
| buttonDescriptor | CustomButtonDescriptor | The description of the button. |
getTitle()
Reads the title on the attachment card. Typically this will be a filename.
Returns a string
getDownloadURL()
This method is deprecated. Please use the same-named method on the AttachmentCardClickEvent object instead.
Returns a Promise<string>
getMessageView()
Get the MessageView that this attachment card belongs to if it belongs to one. AttachmentCardViews in Gmail always belong to a MessageView.
Returns null or a MessageView
Events
destroy
Fires when the view card is destroyed.
Properties
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| destroyed | boolean | This property is set to true once the view is destroyed. | Yes |
AttachmentCardClickEvent
This object is given to the onClick function defined in a CustomButtonDescriptor added to an AttachmentCardView.
getDownloadURL()
Get the URL for the attachment card's download link as a promise for a string. For FILE attachment cards, the URL will be a short-lived URL that can be accessed without cookies. For CUSTOM attachment cards, the URL will be the downloadUrl property of the card's download button if it has one, otherwise null. Other attachment card types may not have a download URL, and the promise may resolve to null.
Returns a Promise<string>
AttachmentIcon
Object that represents an AttachmentIcon returned by addAttachmentIcon in message view.
tooltipShown
Fires when mouse enters message attachment icon to show custom tooltip html element.
tooltipHidden
Fires when mouse leaves message attachment icon to hide custom tooltip html element.
AttachmentCardOptions
This type is accepted by the MessageView.addAttachmentCardView() method to insert an AttachmentCardView for a message. An attachment card offers a way to display a rich preview of any 'attachment' to a message. Note that 'attachments' is referenced in the generic sense and need not be a downloadable file specifically. One example would be to show you YouTube attachment cards for any YouTube links present in an email.
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| title | string | The title of the attachment card. Typically a filename is set here. | Yes | |
| description | string | A description of the attachment card displayed subtly. | Yes | |
| previewUrl | string | The url of an "open" or "preview" action for this attachment. The attachment cards primary action (clicking on the card) takes the user in a new window to the URL specified here. This is also the URL used if the user right clicks and copies the link address. | Yes | |
| previewThumbnailUrl | string | A URL to an image representing the thumbnail preview of the attachment card | Yes | |
| failoverPreviewIconUrl | string | URL to an icon to fallback on in case the previewThumbnailUrl fails to load. | Yes | |
| previewOnClick | function(event) | A callback to call when the user clicks on the preview area. Note that if the previewUrl is also set, the preview will open in a new window in addition to this callback being called. The PreviewEvent has one property - attachmentCardView. It also has a preventDefault() function. Calling this function prevents the preview from opening in a new window. | Yes | |
| fileIconImageUrl | string | The url of the icon of the attachment. | Yes | |
| buttons | `Array<(DownloadButtonDescriptor | CustomButtonDescriptor)>` | An array of buttons to support functionality in addition to the preview functionality | Yes |
| foldColor | string | The color of the attachment card fold and an accompying accent color. | No | #BEBEBE |
| mimeType | string | The mime type of the attachment if it has one. This is used to render image mime types slightly differently to be consistent with Gmail. Specifically, the previewThumbnailUrl images are rendered full bleed to show as much of the image as possible. As such the hover UI looks slightly different. | No | null |
AttachmentCardNoPreviewOptions
This type is accepted by the MessageView.addAttachmentCardView() method to insert an AttachmentCardView for a message. An attachment card offers a way to display a rich preview of any 'attachment' to a message. Note that 'attachments' is referenced in the generic sense and need not be a downloadable file specifically. One example would be to show you YouTube attachment cards for any YouTube links present in an email.
These options differ from AttachmentCardOptions in that there is no previewThumbnailUrl, instead you use a iconThumbnailUrl to show a generic icon. These are rendered and positioned slightly differently than preview images.
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| title | string | The title of the attachment card. Typically a filename is set here. | Yes | |
| description | string | A description of the attachment card displayed subtly. | Yes | |
| previewUrl | string | The url of an "open" or "preview" action for this attachment. The attachment cards primary action (clicking on the card) takes the user in a new window to the URL specified here. This is also the URL used if the user right clicks and copies the link address. | Yes | |
| iconThumbnailUrl | string | A URL to an icon to show in the thumbnail area of the attachment card | Yes | |
| previewOnClick | function(event) | A callback to call when the user clicks on the preview area. Note that if the previewUrl is also set, the preview will open in a new window in addition to this callback being called. The PreviewEvent has one property - attachmentCardView. It also has a preventDefault() function. Calling this function prevents the preview from opening in a new window. | Yes | |
| fileIconImageUrl | string | The url of the icon of the attachment. | Yes | |
| buttons | `Array<(DownloadButtonDescriptor | CustomButtonDescriptor)>` | An array of buttons to support functionality in addition to the preview functionality. | Yes |
| foldColor | string | The color of the attachment card fold and an accompying accent color. | No | #BEBEBE |
ContentPanelDescriptor
This type is passed into the ThreadView.addSidebarContentPanel() method as a way to configure the content panel shown. ContentPanels are typically shown in a sidebar and when multiple are shown they are displayed in a multi tab interface.
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| el | HTMLElement | The element to display in the content panel. | Yes | |
| title | string | The text to show in the tab. | Yes | |
| iconUrl | string | URL for the icon to show in the tab. Should be a local extension file URL or a HTTPS url. | Yes | |
| appName | string | When a thread is open but the sidebar isn't, then buttons to open the sidebar will be shown next to the thread. Each button may be associated with multiple sidebars. The sidebars are grouped into buttons based on this appName property, their app's appName passed to InboxSDK.load(), or the title property. | No | |
| appIconUrl | string | Overrides the icon for the sidebar-opener button. | No | |
| id | string | A string can be passed to identify this panel so that user preferences specific to this panel may be saved. If this property is not present, then the title will be used as the id. | No | |
| hideTitleBar | boolean | Hide the title bar if this is the only sidebar panel attached to the thread. If multiple panels are added (including panels from other extensions) then the title bar will appear so that the user can adjust the panels with the title bar controls. | No | false |
| orderHint | number | If multiple content panels for your app are added then they will be ordered by this value. | No | 0 |
DownloadButtonDescriptor
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| downloadUrl | string | The url of the file to download when the user presses the download button. | Yes | |
| downloadFilename | string | If the URL is a data: or blob: URI, then this sets the filename for the file to be saved as. This works by setting the "download" attribute on an anchor element to the given value. | No | null |
| onClick | function(event) | A callback that is called when the user presses the download button. Note, this is called in addition to file actually downloading which happens automatically. | Yes | |
| openInNewTab | boolean | Whether the download action should open in a new tab. It may be useful to open a new tab to perform the download if for example you want to sometimes redirect the user to a login or permission page. By default, the SDK will attempt to download the file in the same tab and not open a new one. This is typically a better user experience. | No | false |
CustomButtonDescriptor
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| iconUrl | string | The icon to use. Use a white image with transparent background for consistency. | Yes | |
| tooltip | string | The tooltip to show when the user hovers over the button. | Yes | |
| onClick | function(AttachmentCardClickEvent) | A callback that is called when the user presses the button. | Yes |
AttachmentsToolbarButtonDescriptor
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| tooltip | string | The tooltip of the button. | Yes | |
| iconUrl | string | The url of an icon image to use. A black icon with transparent background is preferred. | Yes | |
| onClick | function(event) | The callback when the button is clicked. The event object has a property event.attachmentCardViews which is an array of AttachmentCardViews. | Yes |
MessageViewLinkDescriptor
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| text | string | The anchor text of the link. | Yes | |
| html | string | The html string of the link found. | Yes | |
| element | HTMLElement | The actual HTMLElement of the link found. | Yes | |
| href | string | The url of the link. | Yes | |
| isInQuotedArea | boolean | Whether the link was found in the qouted area of the message or not | Yes |
MessageAttachmentIconDescriptor
This type is used to describe a button you add to a MessageView.
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| iconUrl | string | URL for the icon to show on in the attachments column. Should be a local extension file URL or a HTTPS URL. | Yes | |
| iconClass | string | A CSS class to apply to the icon. | No | MODIFIER |
| iconHtml | string | An optional Html for the icon to show. This property can not be used with iconUrl. | No | null |
| tooltip | string or HTMLElement | The tooltip text or custom tooltip element to show when the user hovers over the icon. | Yes | |
| onClick | function | Function to call when the user clicks the icon. | No |
MessageViewToolbarButtonDescriptor
The options to use to configure buttons added to the message.
| Property | Type | Description | Required? | Default |
|---|---|---|---|---|
| section | MessageViewToolbarSectionNames | The section of the message to place the button. | Yes | |
| title | string | Text to show on the menu item. | Yes | |
| iconUrl | string | URL for the icon to show on the menu item. Should be a local extension file URL or a HTTPS URL. The image will be displayed with a height and width of 16px. | Yes | |
| iconClass | string | An optional class to apply to the icon. | No | |
| onClick | function | This is called when the menu item is clicked. | Yes | |
| orderHint | number | Used to specify the order of added menu items. | Yes |
Enums and Constants
MessageViewViewStates
The various UI states a MessageView can be in.
| Enum | Description |
|---|---|
| HIDDEN | In this state none of the message is visible except for the outline of its existence. |
| COLLAPSED | In this state most of the body of the message is not visible and some recipients may not be showing. |
| EXPANDED | In this state all of the message is visible including the body. |
MessageViewToolbarSectionNames
The locations that a button can be added to on a MessageView.
| Enum | Description |
|---|---|
| MORE | The button will be added to the message's "More" dropdown menu. |