This document explains how to create and send email messages using the Gmail API.
There are two ways to send email using the Gmail API:
- You can send it directly using the
messages.sendmethod. - You can send it from a draft, using the
drafts.sendmethod. For more information on sending a draft message, see Send drafts.
Gmail messages are sent as base64URL encoded strings within the
raw
field of a messages
resource. To send an email message:
- Create the email content and encode it as a base64URL string.
- Create a new message resource and set its
rawproperty to the base64URL string you just created. - Call the
messages.sendmethod, or, if sending a draft, call thedrafts.sendmethod, to send the message.
The details of this workflow can vary depending on your choice of client library and programming language.
Create messages
The Gmail API requires MIME email messages compliant with RFC 2822 and encoded as base64URL strings. Many programming languages have libraries or utilities that simplify the process of creating and encoding MIME messages.
The following code samples show how to create a MIME message using Google API client libraries for various languages:
Java
Creating an email message can be simplified with the MimeMessage class in
the javax.mail.internet package. The following code sample shows how to
create the email message, including the headers:
Next, encode the MimeMessage, instantiate a messages object, and set the
base64URL encoded message string as the value of the raw property.
Python
The following code sample shows how to create a MIME message, encode it to a
base64URL string, and assign it to the raw field of the messages
resource:
cURL
curl --request POST \
'https://gmail.googleapis.com/gmail/v1/users/me/drafts' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"message":{"raw":"MESSAGE"}}'
Replace the following:
ACCESS_TOKEN: the access token that grants access to the API.MESSAGE: the RFC 2822 formatted MIME message, encoded as base64URL.
Create messages with attachments
Creating a message with an attachment is like creating any other message, but the process of uploading the file as a multi-part MIME message depends on the programming language.
The following code samples show possible ways of creating a multi-part MIME message with an attachment:
Java
The following code sample shows how to create a multi-part MIME message. The encoding and assignment steps are the same as create messages.
Python
Similar to the create messages example, this example
also handles encoding the message to base64URL and assigning it to the raw
field of the messages resource.
cURL
curl --request POST \
'https://gmail.googleapis.com/gmail/v1/users/me/drafts' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"message":{"raw":"MESSAGE"}}'
Replace the following:
ACCESS_TOKEN: the access token that grants access to the API.MESSAGE: the RFC 2822 formatted MIME message containing an attachment, encoded as base64URL.
Send messages
Once you have created a message, you can send it by supplying it in the request
body of the
messages.send
method, as shown in the following examples:
Java
Python
cURL
curl --request POST \
'https://gmail.googleapis.com/gmail/v1/users/me/messages/send' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"raw":"MESSAGE"}'
Replace the following:
ACCESS_TOKEN: the access token that grants access to the API.MESSAGE: the RFC 2822 formatted MIME message, encoded as base64URL.
If you're trying to send a reply and want the email to be grouped into a thread, make sure that:
- The
Subjectheaders match - The
ReferencesandIn-Reply-Toheaders follow the RFC 2822 standard.