Google Mail Source
Provided by: "Apache Software Foundation"
Support Level for this Kamelet is: "Stable"
Receives the emails of a Gmail mailbox that match a search, by default the unread ones, one message per email, and marks each email as read once it has been processed.
Use it to act on incoming email, for example to open a ticket for each email sent to a support address, or to collect orders or invoices that arrive by mail.
Output: the body is the text of the email (its first part with content, such as the plain text part) as JSON text, that is the text in double quotes with JSON escapes. The headers give the subject (CamelGoogleMailStreamSubject), the sender (CamelGoogleMailStreamFrom), the recipients (CamelGoogleMailStreamTo, CamelGoogleMailStreamCc, CamelGoogleMailStreamBcc) and the Gmail ID of the email (CamelGoogleMailId). With raw set to true, the body is the whole email instead, with its attachments, encoded in base64url, as JSON text, and only the Gmail ID is set as a header.
Good to know: it reads the emails that match query, by default the unread ones. With markAsRead set to false and the default query, the same emails are read again on every poll. An email whose processing fails is marked as unread again. Each poll reads up to maxResults emails, 10 by default. It logs in to Google either with OAuth (an OAuth client of a Google Cloud project, and an access token and a refresh token of the Gmail account), or with the key of a service account in serviceAccountKey together with scopes, which reads the mailbox of the user in delegate.
Configuration Options
The following table summarizes the configuration options available for the google-mail-source Kamelet:
| Property | Name | Description | Type | Default | Example |
|---|---|---|---|---|---|
Application Name | Required A name for your application, sent to Google with each call, such as | string | my-company-mail/1.0 | ||
Index | Required Any name for this reader of the mailbox, such as | string | support | ||
Access Token | An OAuth 2 access token of the Gmail account, with access to read and change its emails. It expires after about an hour; the Kamelet then gets a new one with | string | |||
Client ID | The client ID of an OAuth client, created in the Google Cloud console under APIs & Services > Credentials, in a project where the Gmail API is enabled. Not needed when logging in with | string | |||
Client Secret | The client secret of the OAuth client of | string | |||
Delay | How long to wait between two polls of the mailbox, in milliseconds. For example, 60000 is one minute. | integer | 500 | 60000 | |
Delegate User | The email address of the user of your Google Workspace whose mailbox the service account of | string | support@example.com// | ||
Gmail Labels | The names of the Gmail labels to read the emails of, separated by commas, such as | string | INBOX | ||
Mark as Read | If true, each email is marked as read once it has been processed, so that the default query | boolean | true | ||
Max Results | The most emails to read at each poll. When it is not set, 10 is used. | integer | 50 | ||
Gmail Query | A Gmail search, written as in the search box of Gmail, that selects the emails to read. | string | is:unread | is:unread -category:(promotions OR social) | |
Raw Email | If true, the body is the whole email, with its headers and all its parts, such as attachments, in the format of an | boolean | |||
Refresh Token | An OAuth 2 refresh token of the Gmail account, which the Kamelet uses to get a new access token when the current one expires. You get it together with the access token, for example from the Google OAuth 2.0 Playground. Not needed when logging in with | string | |||
Scopes | The permissions to ask Google for, as URLs separated by commas. Needed with | string | https://www.googleapis.com/auth/gmail.modify | ||
Service Account Key | The JSON key of a Google service account, to log in with instead of OAuth: | string | file:/etc/google/service-account.json |
Dependencies
At runtime, the google-mail-source Kamelet relies upon the presence of the following dependencies:
-
camel:jackson3
-
camel:kamelet
-
camel:google-mail
Camel JBang usage
Prerequisites
-
You’ve installed JBang.
-
You have executed the following command:
jbang app install camel@apache/camel Supposing you have a file named route.yaml with this content:
- route:
from:
uri: "kamelet:google-mail-source"
parameters:
.
.
.
steps:
- to:
uri: "kamelet:log-sink" You can now run it directly through the following command
camel run route.yaml Google Mail Source Kamelet Description
Authentication methods
The Kamelet logs in to Google in one of two ways:
-
With OAuth 2.0:
clientIdandclientSecretof an OAuth client from your Google Cloud Console application, anaccessTokenfor immediate access (it expires after about an hour) and arefreshTokento get new ones. -
With a service account: its JSON key in
serviceAccountKey, asfile:<path>,classpath:<resource>orbase64:<Base64 of the key file>. It reads the mailbox of the user of your Google Workspace indelegate, and needsscopes, such ashttps://www.googleapis.com/auth/gmail.modify, which marking the emails as read needs. A Workspace administrator must first allow the client ID of the service account, with these scopes, under Security > Access and data control > API controls > Domain-wide delegation. The service account key is only used whenclientSecretis not set; do not setscopeswith OAuth.
An application name of your choice is sent to Google with each call.
Output format
The body is the text of the mail (its first part with content, such as the plain text part) as JSON text, that is the text in double quotes with JSON escapes. With raw set to true, the body is instead the whole email, with its attachments, in the format of an .eml file (RFC 2822), encoded in base64url, as JSON text; the subject, sender and recipient headers are then not set.
It supports two output data types:
-
json: Json representation of a Google Mail event object
-
cloudevents: Output data as CloudEvent V1 format with specific headers
Headers
When processing mail messages, the following headers are set:
-
CamelGoogleMailId: The ID of the message -
CamelGoogleMailStreamTo: The recipient of the message -
CamelGoogleMailStreamFrom: The emitter of the message -
CamelGoogleMailStreamCc: The carbon copy of the message -
CamelGoogleMailStreamBcc: The blind carbon copy of the message -
CamelGoogleMailStreamSubject: The subject of the message
For CloudEvents output format, additional headers are set: - CamelCloudEventID: The Camel exchange id set as event id - CamelCloudEventType: The event type (default: "org.apache.camel.event.google.mail.stream.consume") - CamelCloudEventSource: The event source (Mail From with prefix "google.mail.stream.") - CamelCloudEventSubject: The event subject - CamelCloudEventTime: The exchange creation timestamp as event time
Configuration
The Kamelet requires the following parameters:
-
index: An index for the google mail endpoint -
applicationName: Google Mail application name
To log in with OAuth:
-
clientId: Client ID of the gmail application -
clientSecret: Client Secret of the gmail application -
accessToken: OAuth 2 access token -
refreshToken: OAuth 2 refresh token for long term usage
To log in with a service account:
-
serviceAccountKey: The JSON key of the service account, such asfile:/etc/google/service-account.json -
delegate: The email address of the user whose mailbox to read -
scopes: The permissions to ask for, such ashttps://www.googleapis.com/auth/gmail.modify
Optional parameters: - delay: The number of milliseconds before the next poll (default: 500) - markAsRead: Mark the message as read once it has been consumed (default: true) - query: The query to execute on gmail box (default: "is:unread", example: "is:unread -category:(promotions OR social)") - labels: Comma separated list of labels to take into account (example: "INBOX"); when it is not set, the emails are not filtered by label - maxResults: The most emails to read at each poll (default: 10) - raw: The body is the whole email with its attachments, encoded in base64url (default: false)
Usage example
apiVersion: camel.apache.org/v1alpha1
kind: KameletBinding
metadata:
name: google-mail-source-binding
spec:
source:
ref:
kind: Kamelet
apiVersion: camel.apache.org/v1alpha1
name: google-mail-source
properties:
index: "messages"
clientId: "{{client-id}}"
clientSecret: "{{client-secret}}"
accessToken: "{{access-token}}"
refreshToken: "{{refresh-token}}"
applicationName: "My Mail App"
delay: 1000
markAsRead: true
labels: "inbox"
query: "is:unread -category:(promotions OR social)"
sink:
ref:
kind: Service
apiVersion: v1
name: my-service Example with a Service Account and Attachments
Reads the unread emails of support@example.com, at most 20 at each poll, as whole emails with their attachments. Each body is a JSON string; remove the quotes and decode it as base64url to get the .eml content.
- route:
from:
uri: "kamelet:google-mail-source"
parameters:
index: "support"
applicationName: "my-company-mail/1.0"
serviceAccountKey: "file:/etc/google/service-account.json"
delegate: "support@example.com"
scopes: "https://www.googleapis.com/auth/gmail.modify"
maxResults: 20
raw: true
delay: 60000
steps:
- to:
uri: "kamelet:log-sink"