Criar e enviar rascunhos de e-mail

Este documento explica como criar, atualizar e enviar e-mails em rascunho usando a API Gmail.

Os rascunhos de e-mail representam mensagens não enviadas com o rótulo do sistema DRAFT aplicado. A mensagem no rascunho não pode ser editada depois de criada, mas pode ser substituída. Nesse sentido, o recurso drafts é um container que fornece um ID estável porque os IDs de mensagem subjacentes mudam sempre que a mensagem é substituída.

O recurso messages em um rascunho tem um comportamento semelhante ao de outras mensagens, exceto pelas seguintes diferenças:

  • As mensagens em rascunho não podem ter nenhum marcador além do marcador do sistema DRAFT.
  • Quando o rascunho é enviado, ele é excluído automaticamente, e uma nova mensagem com um ID atualizado é criada com o marcador do sistema SENT. Essa mensagem é retornada na resposta do método drafts.send.

Criar rascunhos

Seu app pode criar rascunhos usando o método drafts.create. Para criar um rascunho:

  1. Crie uma mensagem MIME que esteja em conformidade com a RFC 2822.
  2. Converta a mensagem em uma string codificada em base64URL.
  3. Chame o método drafts.create, definindo o valor do campo messages.raw como a string codificada.

Os exemplos de código a seguir demonstram o processo:

Java

gmail/snippets/src/main/java/CreateDraft.java
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.gmail.Gmail;
import com.google.api.services.gmail.GmailScopes;
import com.google.api.services.gmail.model.Draft;
import com.google.api.services.gmail.model.Message;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.util.Properties;
import javax.mail.MessagingException;
import javax.mail.Session;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;
import org.apache.commons.codec.binary.Base64;

/* Class to demonstrate the use of Gmail Create Draft API */
public class CreateDraft {
  /**
   * Create a draft email.
   *
   * @param fromEmailAddress - Email address to appear in the from: header
   * @param toEmailAddress   - Email address of the recipient
   * @return the created draft, {@code null} otherwise.
   * @throws MessagingException - if a wrongly formatted address is encountered.
   * @throws IOException        - if service account credentials file not found.
   */
  public static Draft createDraftMessage(String fromEmailAddress,
                                         String toEmailAddress)
      throws MessagingException, IOException {
        /* Load pre-authorized user credentials from the environment.
        TODO(developer) - See https://developers.google.com/identity for
         guides on implementing OAuth2 for your application.*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(GmailScopes.GMAIL_COMPOSE);
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

    // Create the gmail API client
    Gmail service = new Gmail.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Gmail samples")
        .build();

    // Create the email content
    String messageSubject = "Test message";
    String bodyText = "lorem ipsum.";

    // Encode as MIME message
    Properties props = new Properties();
    Session session = Session.getDefaultInstance(props, null);
    MimeMessage email = new MimeMessage(session);
    email.setFrom(new InternetAddress(fromEmailAddress));
    email.addRecipient(javax.mail.Message.RecipientType.TO,
        new InternetAddress(toEmailAddress));
    email.setSubject(messageSubject);
    email.setText(bodyText);

    // Encode and wrap the MIME message into a gmail message
    ByteArrayOutputStream buffer = new ByteArrayOutputStream();
    email.writeTo(buffer);
    byte[] rawMessageBytes = buffer.toByteArray();
    String encodedEmail = Base64.encodeBase64URLSafeString(rawMessageBytes);
    Message message = new Message();
    message.setRaw(encodedEmail);

    try {
      // Create the draft message
      Draft draft = new Draft();
      draft.setMessage(message);
      draft = service.users().drafts().create("me", draft).execute();
      System.out.println("Draft id: " + draft.getId());
      System.out.println(draft.toPrettyString());
      return draft;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 403) {
        System.err.println("Unable to create draft: " + e.getMessage());
      } else {
        throw e;
      }
    }
    return null;
  }
}

Python

gmail/snippet/send mail/create_draft.py
import base64
from email.message import EmailMessage

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def gmail_create_draft():
  """Create and insert a draft email.
   Print the returned draft's message and id.
   Returns: Draft object, including draft id and message meta data.

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create gmail api client
    service = build("gmail", "v1", credentials=creds)

    message = EmailMessage()

    message.set_content("This is automated draft mail")

    message["To"] = "gduser1@workspacesamples.dev"
    message["From"] = "gduser2@workspacesamples.dev"
    message["Subject"] = "Automated draft"

    # encoded message
    encoded_message = base64.urlsafe_b64encode(message.as_bytes()).decode()

    create_message = {"message": {"raw": encoded_message}}
    # pylint: disable=E1101
    draft = (
        service.users()
        .drafts()
        .create(userId="me", body=create_message)
        .execute()
    )

    print(f'Draft id: {draft["id"]}\nDraft message: {draft["message"]}')

  except HttpError as error:
    print(f"An error occurred: {error}")
    draft = None

  return draft


if __name__ == "__main__":
  gmail_create_draft()

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"}}'

Substitua:

  • ACCESS_TOKEN: o token de acesso que concede acesso à API.
  • MESSAGE: a mensagem MIME formatada em RFC 2822, codificada como base64URL.

Atualizar rascunho

Assim como na criação de um rascunho, para atualizar um rascunho, você precisa fornecer um recurso drafts no corpo da solicitação com o campo messages.raw definido como uma string codificada em base64URL que contém a mensagem MIME. Como as mensagens não podem ser atualizadas, a mensagem contida no rascunho é destruída e substituída pela nova mensagem MIME fornecida na solicitação de atualização.

Para recuperar a mensagem MIME atual contida no rascunho, chame o método drafts.get com o parâmetro de consulta format=raw.

Para mais informações, consulte o método drafts.update.

Enviar rascunhos

Ao enviar um rascunho, você pode enviá-lo como está ou fornecer atualizações na solicitação de envio.

Para atualizar o rascunho ao enviar, forneça um recurso drafts no corpo da solicitação do método drafts.send. No recurso drafts, especifique o id do rascunho a ser enviado e defina o campo messages.raw como a nova mensagem MIME codificada como uma string base64URL.

Para saber como enviar uma mensagem do Gmail, consulte Enviar mensagens.