= Google Mail Component
:doctitle: Google Mail
:shortname: google-mail
:artifactid: camel-google-mail
:description: Manage messages in Google Mail.
:since: 2.15
:supportlevel: Stable
:tabs-sync-option:
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:group: Google
:camel-spring-boot-name: google-mail

*Since Camel {since}*

*{component-header}*

The Google Mail component provides access
to http://gmail.com/[Gmail] via
the https://developers.google.com/gmail/api/v1/reference/[Google Mail
Web APIs].

Google Mail uses
the https://developers.google.com/accounts/docs/OAuth2[OAuth 2.0
protocol] for authenticating a Google account and authorizing access to
user data. Before you can use this component, you will need
to https://developers.google.com/gmail/api/auth/web-server[create an
account and generate OAuth credentials]. Credentials consist of a
`clientId`, `clientSecret`, and a `refreshToken`. A handy resource for
generating a long-lived `refreshToken` is
the https://developers.google.com/oauthplayground[OAuth playground].

In the case of a https://developers.google.com/identity/protocols/oauth2#serviceaccount[service account],
credentials consist of a JSON-file (serviceAccountKey). You can also use
https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority[delegation domain-wide authority]
(delegate) and one, several, or all possible
https://developers.google.com/gmail/api/auth/scopes[GMail API Auth Scopes].

Maven users will need to add the following dependency to their pom.xml
for this component:

[source,xml]
----
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-google-mail</artifactId>
    <!-- use the same version as your Camel core version -->
    <version>x.y.z</version>
</dependency>
----

== URI Format

The GoogleMail Component uses the following URI format:

----
google-mail://endpoint-prefix/endpoint?[options]
----

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
include::partial$component-endpoint-headers.adoc[]
// component options: END

[NOTE]
====
This is an API-based component, so per-call parameters can be supplied through `Camel`-prefixed
exchange headers in addition to the endpoint options. If the route consumes messages from untrusted
producers, strip these internal headers at the trust boundary -- for example with
`removeHeaders("Camel*")` -- before the message reaches this component, so that a sender cannot
override the API call. See xref:manual::security-model.adoc[the Camel security model] for details.
====

== Data Type Transformer: update-message-labels

The `google-mail:update-message-labels` data type transformer builds a `ModifyMessageRequest` from exchange variables, resolving label names to Gmail label IDs automatically.

This is useful for modifying Gmail message labels (categorizing, archiving, starring, moving, etc.) without manually calling the labels/list API.

=== Exchange Variables

[cols="1,1,3"]
|===
| Variable | Type | Description

| `addLabels`
| `String` (comma-separated) or `List<String>`
| Label names to add to the message.

| `removeLabels`
| `String` (comma-separated) or `List<String>`
| Label names to remove from the message.
|===

At least one of the two variables must be set.

Both system labels (INBOX, UNREAD, STARRED, SPAM, TRASH, IMPORTANT, etc.) and custom user-defined labels are resolved via the Gmail labels/list API.

=== Examples

[tabs]
====
Java::
+
[source,java]
----
from("google-mail-stream:0")
    .setVariable("addLabels", constant("Work"))
    .setVariable("removeLabels", constant("INBOX,UNREAD"))
    .transformDataType(new DataType("google-mail:update-message-labels"))
    .to("google-mail:messages/modify");
----

YAML::
+
[source,yaml]
----
- route:
    from:
      uri: "google-mail-stream:0"
    steps:
      - setVariable:
          name: addLabels
          constant: "Work"
      - setVariable:
          name: removeLabels
          constant: "INBOX,UNREAD"
      - transformDataType:
          toType: "google-mail:update-message-labels"
      - to:
          uri: "google-mail:messages/modify"
----

XML::
+
[source,xml]
----
<route>
    <from uri="google-mail-stream:0"/>
    <setVariable name="addLabels">
        <constant>Work</constant>
    </setVariable>
    <setVariable name="removeLabels">
        <constant>INBOX,UNREAD</constant>
    </setVariable>
    <transformDataType toType="google-mail:update-message-labels"/>
    <to uri="google-mail:messages/modify"/>
</route>
----
====
== Data Type Transformer: draft

The `google-mail:draft` transformer converts a String body into a Gmail `Draft` using mail headers from the exchange.

It works with `google-mail-stream`, which sets headers like `threadId`, `messageId`, `from`, `to`, `cc`, `bcc`, and `subject` automatically when consuming messages.
You can also set these headers manually to create drafts from scratch.

=== Headers

The transformer reads the following headers:

[cols="1,1,3"]
|===
| Header | Type | Description

| `CamelGoogleMailStreamThreadId`
| `String`
| Thread ID for the conversation (optional, used for replies)

| `CamelGoogleMailStreamMessageId`
| `String`
| Message ID to reply to (optional, sets In-Reply-To and References headers)

| `CamelGoogleMailStreamFrom`
| `String`
| From address (optional)

| `CamelGoogleMailStreamTo`
| `String`
| To address (optional)

| `CamelGoogleMailStreamCc`
| `String`
| CC address (optional)

| `CamelGoogleMailStreamBcc`
| `String`
| BCC address (optional)

| `CamelGoogleMailStreamSubject`
| `String`
| Email subject (optional)
|===

All headers are optional.

=== Message Body

The message body is a `String` with the email content (plain text or HTML).

Content type defaults to `text/plain; charset=UTF-8`. For HTML, set `Exchange.CONTENT_TYPE` to `text/html; charset=UTF-8`.

The transformer:

* Builds an RFC 2822 MIME message and encodes it as Base64 URL-safe (required by Gmail API)
* Sets `In-Reply-To` and `References` headers when `messageId` is present
* Associates the draft with the correct thread when `threadId` is present

=== Examples

[tabs]
====
Java::
+
[source,java]
----
// Create a draft reply from a received message
from("google-mail-stream:0")
    .setBody(constant("Thank you for your message. I will respond soon."))
    .transformDataType(new DataType("google-mail:draft"))
    .to("google-mail:drafts/create?inBody=content");

// Create a new draft (no threading)
from("direct:newDraft")
    .setBody(constant("This is a new draft message"))
    .setHeader("CamelGoogleMailStreamFrom", constant("sender@example.com"))
    .setHeader("CamelGoogleMailStreamTo", constant("recipient@example.com"))
    .setHeader("CamelGoogleMailStreamSubject", constant("New Draft"))
    .transformDataType(new DataType("google-mail:draft"))
    .to("google-mail:drafts/create?inBody=content");
----

YAML::
+
[source,yaml]
----
# Create a draft reply from a received message
- route:
    from:
      uri: "google-mail-stream:0"
    steps:
      - setBody:
          constant: "Thank you for your message. I will respond soon."
      - transformDataType:
          toType: "google-mail:draft"
      - to:
          uri: "google-mail:drafts/create"
          parameters:
            inBody: content

# Create a new draft (no threading)
- route:
    from:
      uri: "direct:newDraft"
    steps:
      - setBody:
          constant: "This is a new draft message"
      - setHeader:
          name: CamelGoogleMailStreamFrom
          constant: "sender@example.com"
      - setHeader:
          name: CamelGoogleMailStreamTo
          constant: "recipient@example.com"
      - setHeader:
          name: CamelGoogleMailStreamSubject
          constant: "New Draft"
      - transformDataType:
          toType: "google-mail:draft"
      - to:
          uri: "google-mail:drafts/create"
          parameters:
            inBody: content
----

XML::
+
[source,xml]
----
<!-- Create a draft reply from a received message -->
<route>
    <from uri="google-mail-stream:0"/>
    <setBody>
        <constant>Thank you for your message. I will respond soon.</constant>
    </setBody>
    <transformDataType toType="google-mail:draft"/>
    <to uri="google-mail:drafts/create?inBody=content"/>
</route>

<!-- Create a new draft (no threading) -->
<route>
    <from uri="direct:newDraft"/>
    <setBody>
        <constant>This is a new draft message</constant>
    </setBody>
    <setHeader name="CamelGoogleMailStreamFrom">
        <constant>sender@example.com</constant>
    </setHeader>
    <setHeader name="CamelGoogleMailStreamTo">
        <constant>recipient@example.com</constant>
    </setHeader>
    <setHeader name="CamelGoogleMailStreamSubject">
        <constant>New Draft</constant>
    </setHeader>
    <transformDataType toType="google-mail:draft"/>
    <to uri="google-mail:drafts/create?inBody=content"/>
</route>
----
====


== More Information

For more information on the endpoints and options see API documentation
at: https://developers.google.com/gmail/api/v1/reference/[https://developers.google.com/gmail/api/v1/reference/]



include::spring-boot:partial$starter.adoc[]
