There are two ways to send email using the Gmail API:
- You can send it directly using the
messages.send
method. - You can send it from a draft, using the
drafts.send
method.
Emails are sent as base64url encoded strings within the raw
property of a
message resource. The high-level
workflow to send an email is to:
- Create the email content in some convenient way and encode it as a base64url string.
- Create a new message resource and set its
raw
property to the base64url string you just created. - Call
messages.send
, or, if sending a draft,drafts.send
to send the message.
The details of this workflow can vary depending on your choice of client library and programming language.
Creating 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 examples demonstrate how to create a MIME message using the Google APIs client libraries for various languages.
Java
Creating an email message can be greatly simplified with the MimeMessage
class in the javax.mail.internet
package. The following example shows how
to create the email message, including the headers:
/**
* Create a MimeMessage using the parameters provided.
*
* @param to email address of the receiver
* @param from email address of the sender, the mailbox account
* @param subject subject of the email
* @param bodyText body text of the email
* @return the MimeMessage to be used to send email
* @throws MessagingException
*/
public static MimeMessage createEmail(String to,
String from,
String subject,
String bodyText)
throws MessagingException {
Properties props = new Properties();
Session session = Session.getDefaultInstance(props, null);
MimeMessage email = new MimeMessage(session);
email.setFrom(new InternetAddress(from));
email.addRecipient(javax.mail.Message.RecipientType.TO,
new InternetAddress(to));
email.setSubject(subject);
email.setText(bodyText);
return email;
}
The next step is to encode the MimeMessage
, instantiate a Message
object, and set the base64url encoded message string as the value of the
raw
property.
/**
* Create a message from an email.
*
* @param emailContent Email to be set to raw of message
* @return a message containing a base64url encoded email
* @throws IOException
* @throws MessagingException
*/
public static Message createMessageWithEmail(MimeMessage emailContent)
throws MessagingException, IOException {
ByteArrayOutputStream buffer = new ByteArrayOutputStream();
emailContent.writeTo(buffer);
byte[] bytes = buffer.toByteArray();
String encodedEmail = Base64.encodeBase64URLSafeString(bytes);
Message message = new Message();
message.setRaw(encodedEmail);
return message;
}
Python
The following code sample demonstrates creating a MIME message, encoding to
a base64url string, and assigning it to the raw
field of the Message
resource:
def create_message(sender, to, subject, message_text):
"""Create a message for an email.
Args:
sender: Email address of the sender.
to: Email address of the receiver.
subject: The subject of the email message.
message_text: The text of the email message.
Returns:
An object containing a base64url encoded email object.
"""
message = MIMEText(message_text)
message['to'] = to
message['from'] = sender
message['subject'] = subject
return {'raw': base64.urlsafe_b64encode(message.as_string())}
Creating 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 examples demonstrate possible ways of creating a multi-part MIME message with an attachment.
Java
The following example shows how to create a multi-part MIME message, the encoding and assignment steps are the same as above.
/**
* Create a MimeMessage using the parameters provided.
*
* @param to Email address of the receiver.
* @param from Email address of the sender, the mailbox account.
* @param subject Subject of the email.
* @param bodyText Body text of the email.
* @param file Path to the file to be attached.
* @return MimeMessage to be used to send email.
* @throws MessagingException
*/
public static MimeMessage createEmailWithAttachment(String to,
String from,
String subject,
String bodyText,
File file)
throws MessagingException, IOException {
Properties props = new Properties();
Session session = Session.getDefaultInstance(props, null);
MimeMessage email = new MimeMessage(session);
email.setFrom(new InternetAddress(from));
email.addRecipient(javax.mail.Message.RecipientType.TO,
new InternetAddress(to));
email.setSubject(subject);
MimeBodyPart mimeBodyPart = new MimeBodyPart();
mimeBodyPart.setContent(bodyText, "text/plain");
Multipart multipart = new MimeMultipart();
multipart.addBodyPart(mimeBodyPart);
mimeBodyPart = new MimeBodyPart();
DataSource source = new FileDataSource(file);
mimeBodyPart.setDataHandler(new DataHandler(source));
mimeBodyPart.setFileName(file.getName());
multipart.addBodyPart(mimeBodyPart);
email.setContent(multipart);
return email;
}
Python
Similar to the previous example, this example also handles encoding the
message to base64url and assigning it to the raw
field of the Message
resource.
def create_message_with_attachment(
sender, to, subject, message_text, file):
"""Create a message for an email.
Args:
sender: Email address of the sender.
to: Email address of the receiver.
subject: The subject of the email message.
message_text: The text of the email message.
file: The path to the file to be attached.
Returns:
An object containing a base64url encoded email object.
"""
message = MIMEMultipart()
message['to'] = to
message['from'] = sender
message['subject'] = subject
msg = MIMEText(message_text)
message.attach(msg)
content_type, encoding = mimetypes.guess_type(file)
if content_type is None or encoding is not None:
content_type = 'application/octet-stream'
main_type, sub_type = content_type.split('/', 1)
if main_type == 'text':
fp = open(file, 'rb')
msg = MIMEText(fp.read(), _subtype=sub_type)
fp.close()
elif main_type == 'image':
fp = open(file, 'rb')
msg = MIMEImage(fp.read(), _subtype=sub_type)
fp.close()
elif main_type == 'audio':
fp = open(file, 'rb')
msg = MIMEAudio(fp.read(), _subtype=sub_type)
fp.close()
else:
fp = open(file, 'rb')
msg = MIMEBase(main_type, sub_type)
msg.set_payload(fp.read())
fp.close()
filename = os.path.basename(file)
msg.add_header('Content-Disposition', 'attachment', filename=filename)
message.attach(msg)
return {'raw': base64.urlsafe_b64encode(message.as_string())}
Sending messages
Once you have created a message, you can send it by supplying it in the
request body of a call to
messages.send
, as demonstrated
in the following examples.
Java
/**
* Send an email from the user's mailbox to its recipient.
*
* @param service Authorized Gmail API instance.
* @param userId User's email address. The special value "me"
* can be used to indicate the authenticated user.
* @param emailContent Email to be sent.
* @return The sent message
* @throws MessagingException
* @throws IOException
*/
public static Message sendMessage(Gmail service,
String userId,
MimeMessage emailContent)
throws MessagingException, IOException {
Message message = createMessageWithEmail(emailContent);
message = service.users().messages().send(userId, message).execute();
System.out.println("Message id: " + message.getId());
System.out.println(message.toPrettyString());
return message;
}
Python
def send_message(service, user_id, message):
"""Send an email message.
Args:
service: Authorized Gmail API service instance.
user_id: User's email address. The special value "me"
can be used to indicate the authenticated user.
message: Message to be sent.
Returns:
Sent Message.
"""
try:
message = (service.users().messages().send(userId=user_id, body=message)
.execute())
print 'Message Id: %s' % message['id']
return message
except errors.HttpError, error:
print 'An error occurred: %s' % error
If you're trying to send a reply and want the email to thread, make sure that:
- The
Subject
headers match - The
References
andIn-Reply-To
headers follow the RFC 2822 standard.
For information on sending a message from a draft, see Creating Drafts.