Gmail integration

Back to list of integrations

Use the Gmail integration to let agents send, reply to, draft, find, and read email, and request approvals by email, through Action Tools.

Authentication	Actions	Triggers
OAuth 2.0	(7)	(4)

​

Supported actions

Action	Use it to
Send Email	Send an email, or save it as a draft.
Request Approval in Email	Send an approval request and wait for the recipient to approve or reject it.
Reply to Email	Reply to the sender or to all recipients of a message.
Create Draft Reply	Save a reply as a draft without sending it.
Get Email	Read a message by its ID.
Find Email	Search messages by sender, recipient, subject, content, label, category, date, or attachment.
Custom API Call	Call any Gmail API endpoint the other actions don’t cover.

​

Triggers

Trigger	Fires when
New Email	New mail arrives in the inbox.
New Labeled Email	A label is added to an email.
New Attachment	An email with an attachment arrives.
New Label	A new label is created.

​

Prerequisites

• A Google Cloud project with the Gmail API enabled and an OAuth consent screen. In Testing status, only test users can authorize and refresh tokens expire after seven days.

​

Set up the integration

1. Create a Google OAuth client

   Create an OAuth client ID of type Web application, add the Artemis Callback URL to Authorized redirect URIs, and copy the Client ID and Client Secret. See Using OAuth 2.0 to access Google APIs.

2. Create the auth profile

   In Integrations, select Gmail > Connect. On Project Auth Profiles, select New Profile > Integration Profile > Gmail > Continue. Enter the Client ID and Client Secret, select Create Profile, and then select Authorize.

   Artemis pre-fills the Google endpoints, the access_type=offline and prompt=consent parameters, and these scopes: gmail.send, gmail.readonly, gmail.compose, and email. Add the same scopes to the consent screen.

   Usage Mode: Preconfigured shares one authorization across users; JIT and Preflight ask each user to authorize, during or before the session. See Auth profiles.

3. Create the action tool

   In Tools, select New Tool > Action > Gmail > Continue. Select the Action and Auth Profile, set parameter defaults (leave a value empty for the agent to supply at runtime), and select Create Tool. Then assign the tool to an agent.

​

Action reference

Send Email

Parameter	Type	Description
receiver	array	Recipient addresses (To).
cc	array	Carbon copy recipients.
bcc	array	Blind carbon copy recipients.
subject	string	Subject line.
body_type	enum	Body type. Default: plain text.
body	string	Message body.
reply_to	array	Addresses for the Reply-To header.
sender_name	string	Display name of the sender.
from	string	Sender address. Must be listed in the Gmail account’s Send mail as settings.
attachments	array	Attachments.
in_reply_to	string	Message-ID to reply to, which threads the message.
draft	boolean	Saves a draft without sending. Default: False.

Request Approval in Email

Sends the request and pauses the tool until the recipient approves or rejects it.

Parameter	Type	Description
receiver	string	Approver’s email address.
cc	array	Carbon copy recipients.
bcc	array	Blind carbon copy recipients.
subject	string	Subject of the approval request.
body	string	Message body.
reply_to	array	Addresses for the Reply-To header.
sender_name	string	Display name of the sender.
from	string	Sender address. Must be listed in the Gmail account’s settings.
in_reply_to	string	Message-ID to reply to.

Reply to Email

Parameter	Type	Description
message_id	enum	Message to reply to. Select from the list or enter an ID.
reply_type	enum	Reply to the sender only or to all recipients. Default: Reply (to sender only).
body_type	enum	Body type. Default: Plain text.
body	string	Reply content.
sender_name	string	Optional sender display name.
attachment	string	Optional file to attach.
attachment_name	string	Custom name for the attachment.

Create Draft Reply

Parameter	Type	Description
message_id	enum	Message to reply to. Select from the list or enter an ID.
reply_type	enum	Reply to the sender only or to all recipients. Default: Reply (to sender only).
body_type	enum	Body type. Default: Plain text.
body	string	Draft reply content.
include_original_message	boolean	Quotes the original message in the draft. Default: True.
sender_name	string	Optional sender display name.
attachment	string	Optional file to attach.
attachment_name	string	Custom name for the attachment.

Get Email

Parameter	Type	Description
message_id	string	ID of the message to read.

Find Email

Provide at least one search filter.

Parameter	Type	Description
from	string	Sender filter.
to	string	Recipient filter.
subject	string	Subject filter.
content	string	Text in the message body.
has_attachment	boolean	Returns only messages with attachments. Default: False.
attachment_name	string	Attachment file name.
label	enum	Label filter.
category	enum	Category filter.
after_date	string	Returns messages sent after this date.
before_date	string	Returns messages sent before this date.
include_spam_trash	boolean	Includes Spam and Trash. Default: False.
max_results	number	Maximum results, from 1 to 500.

Custom API Call

Sends a request to any Gmail API endpoint. Artemis injects the authorization header from the auth profile.

Parameter	Type	Description
url	object	Endpoint URL.
method	enum	HTTP method.
headers	object	Additional request headers.
queryParams	object	Query parameters.
body_type	enum	Body type. Default: None.
body	object	Request body.
response_is_binary	boolean	Turn on for binary responses, such as PDFs or images. Default: False.
failsafe	boolean	Returns no error when the call fails.
timeout	number	Timeout, in seconds.
followRedirects	boolean	Follows HTTP redirects. Default: False.

​

Troubleshoot common issues

Issue	Resolution
redirect_uri_mismatch during authorization	Add the exact Callback URL to the OAuth client’s Authorized redirect URIs.
access_denied or the app isn’t verified	Add the user as a test user, or publish the consent screen.
The profile stops working after seven days	The consent screen is in Testing status. Publish the app, and then authorize again.
403 Insufficient Permission	Confirm the profile’s scopes cover the action, and then authorize again.
Email sends from the wrong address	Set from to an address listed in the account’s Send mail as settings.
Find Email returns an error	Provide at least one search filter.

​

Related articles

• Auth profiles
• Action Tools
• Gmail API documentation