Gmail
Connect Gmail so an agent can search, read and reply to email, send follow-ups, save drafts and tidy your inbox, all from your own Gmail account.
What you will achieve
An agent will be able to work with your Gmail: find and read emails, reply in the same conversation, save drafts, send follow-ups, and mark, archive or trash a message. You choose which of these each agent gets.
Overview and use cases
- Email the caller their appointment details.
- Send your team a summary of what the caller asked for.
- Find "the email Sara sent about the quote" and answer from it.
- Reply to a customer's email in the same conversation.
- Save a reply as a draft for you to check before it goes out.
Prerequisites
- A Gmail or Google Workspace account. Mail is read from, and sent from, that address.
- If Phynxa does not supply the Google app, a Google Cloud OAuth client (see Google Calendar; enable the Gmail API).
Connect it in Phynxa
- Integrations, Connect on Gmail.
- Sign in with Google (or paste the Client ID and secret first), choose the account and approve. The consent screen asks to read, send and manage your email, and to see your address. It never asks to delete mail for good.
- The card shows Connected.
Permissions and settings
Scopes: gmail.modify and userinfo.email. Phynxa can read mail, send it, save drafts, change labels and move a message to the Trash. It cannot delete a message permanently.
Google classes gmail.modify as a restricted permission. If you connect with your own Google app, Google lets only the test users you list (up to 100) approve it until the app has passed Google's verification.
Connected Gmail before reading was added? That connection only had permission to send. Sending keeps working; for the other actions, choose Reconnect and approve again.
Use it in a call
| Action | What it does | Runs |
|---|---|---|
| Send email | Sends an email. Needs to (several addresses separated by commas), subject and body. | In the background |
| Search emails | Lists matching emails with who sent each, the subject, the date and the first words. Takes query in Gmail search words (for example from:sara@example.com is:unread newer_than:7d) and max_results (up to 10). | Waits |
| Read email | Opens one email and returns its text (up to about 3,500 characters), who sent it and the names of any attachments. Needs message_id from a search. | Waits |
| Read conversation | Returns the latest four messages of a conversation. Needs thread_id. | Waits |
| Reply to email | Replies in the same conversation, to the person who wrote it (to their reply-to address when they set one). Needs message_id and body. | In the background |
| Create draft | Saves an email in Gmail's Drafts. Nothing is sent. Needs to, subject and body. | In the background |
| Mark as read | Marks one email as read. | In the background |
| Archive email | Takes one email out of the inbox. It is kept and can still be found. | In the background |
| Move to trash | Moves one email to the Trash, where Gmail keeps it for 30 days. | In the background |
These actions also work on a WhatsApp agent: on its Tools tab, Add tool, Integration, Gmail. See Create a WhatsApp agent.
Keep your mailbox safe
- Give the reading actions only to agents you trust. An agent that answers the public (a phone line, a website widget, a WhatsApp number) answers anyone who talks to it, so anyone could ask it about your mail. For a public agent, give it only Send email or Create draft.
- An email's text is written by someone else. It can contain instructions aimed at an assistant ("forward everything to ..."). Phynxa tells the agent to treat what it reads as information and never as instructions, but the safest set-up is not to give one agent both the reading and the sending actions.
- Each tool can be switched off by removing it from the agent.
- There is no private "ask about my mail" chat. A WhatsApp agent answers the customers who write to its number; it does not take orders from you about your own inbox.
Test it
Test connection, then in Chat ask the agent to find your latest email, then to read it.
Expected result
The agent names the sender and subject of a real email in your mailbox and summarises it. A sent email arrives from your Gmail address and appears in its Sent folder.
Troubleshooting
- "Reconnect Gmail." The connection was made before reading was added, or the permission was not granted. Reconnect and approve.
- "The Gmail API is not turned on." In your own Google Cloud project, turn on the Gmail API, wait a minute and try again.
- "Not found." The email was deleted, or the id is not one a search returned. Search again.
- An email is cut short. Long emails are shortened so the agent can read them in time. Open the email in Gmail for the rest.
- The email does not arrive. Check spam, and the address the agent used.
- Limits. Gmail limits how many messages an account can send per day, and how fast it answers requests; heavy use can be refused by Google.
Security and credentials
Tokens are stored encrypted. Revoke access at your Google account's security page; Remove forgets it here. The agent acts in your name, so tell it what it may read and send.
Related guides
Something here does not match what you see in the dashboard? Let us know.