Mail Received

Run when Gmail delivers mail for a connected mailbox and labels.

Type

google.gmail.on-mail

Messaging

ServiceRequired

Google

CapabilityRequired

Gmail

Listed only when a matching connected service is enabled.

Mail Received runs when Gmail push notifications arrive for the configured mailbox.

Payload

Field	Type	Description
`serviceId`	string	Connected Google service with Gmail enabled
`labelIds`	string	Labels to watch. Default: `["INBOX"]`

Trigger data

Available as args.*.

Field	Type	Description
`message.id`	string	Gmail message id
`message.threadId`	string	Thread id
`message.labelIds`	string	Message labels
`message.snippet`	string	Snippet
`message.internalDate`	string	Internal date
`message.subject`	string	Subject
`message.from.name`	string	From name
`message.from.email`	string	From email
`message.to[].name`	string	To name
`message.to[].email`	string	To email
`message.cc[].name`	string	Cc name
`message.cc[].email`	string	Cc email
`message.bcc[].name`	string	Bcc name
`message.bcc[].email`	string	Bcc email
`message.replyTo.name`	string	Reply-to name
`message.replyTo.email`	string	Reply-to email
`message.messageId`	string	Message-ID header
`message.inReplyTo`	string	In-Reply-To header
`message.references`	string	References header
`message.isReply`	boolean	Whether the message is a reply
`message.dateHeader`	string	Date header
`message.textPlain`	string	Plain-text body
`message.textHtml`	string	HTML body
`message.textParsed`	string	Parsed body
`message.attachments[].filename`	string	Attachment filename
`message.attachments[].mimeType`	string	Attachment MIME type
`message.attachments[].size`	number	Attachment size
`message.attachments[].attachmentId`	string	Attachment id
`raw`	object	Original Gmail push payload

Use case

Inbound support or sales mail should create or update a table row, classify with an AI Field or agent, then notify — without opening a live chat.
Watch INBOX or other labels (for example only support@) so personal mail does not fire the handler.
Store threadId on a Gmail Thread column so later replies stay on the same conversation in Gmail.
Use Get Attachment when inbound mail includes files you need in workspace storage.
Use Mail Chat instead when a person should talk to a default agent over email.

Channels vs handlers

Mail handlers share identifiers with Mail Chat.

If an active channel uses the same mailbox, inbound mail goes to the channel. The event handler does not run for that mailbox until you disable or change the channel, or change the handler identifier.