建立及傳送電子郵件草稿

本文說明如何使用 Gmail API 建立、更新及傳送電子郵件草稿。

電子郵件草稿是指套用 DRAFT 系統標籤的未傳送郵件。 草稿建立後，其中的訊息內容就無法編輯，但可以替換。就這個意義來說，drafts 資源是提供穩定 ID 的容器，因為基礎訊息 ID 會在每次訊息遭到取代時變更。

草稿中的 messages 資源行為與其他郵件類似，但有以下差異：

  • 草稿郵件只能有 DRAFT 系統標籤，不得有其他標籤。
  • 傳送草稿後，系統會自動刪除草稿，並建立含有更新 ID 的新郵件，且附上 SENT 系統標籤。這則訊息會以 drafts.send 方法回應的形式傳回。

建立草稿

您的應用程式可以使用 drafts.create 方法建立草稿。如要撰寫草稿，請按照下列步驟操作：

  1. 建立符合 RFC 2822 規範的 MIME 郵件。
  2. 將訊息轉換為 base64URL 編碼字串。
  3. 呼叫 drafts.create 方法，將 messages.raw 欄位的值設為編碼字串。

以下程式碼範例說明這個程序：

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

更改下列內容：

  • ACCESS_TOKEN：授予 API 存取權的存取權杖。
  • MESSAGE：以 RFC 2822 格式設定的 MIME 郵件，並以 base64URL 編碼。

更新草稿

與建立草稿類似，如要更新草稿，您必須在要求主體中提供 drafts 資源，並將 messages.raw 欄位設為包含 MIME 郵件的 base64URL 編碼字串。由於訊息無法更新，因此系統會刪除草稿中的訊息，並以更新要求中提供的新 MIME 訊息取代。

如要擷取草稿中目前的 MIME 訊息，請使用查詢參數 format=raw 呼叫 drafts.get 方法。

詳情請參閱 drafts.update 方法。

傳送草稿

傳送草稿時，您可以直接傳送，也可以在傳送要求中提供更新。

如要在傳送時更新草稿，請在 drafts.send 方法的要求主體中提供 drafts 資源。在 drafts 資源中，您必須指定要傳送的草稿 id，並將 messages.raw 欄位設為以 base64URL 字串編碼的新 MIME 郵件。

如要瞭解如何傳送 Gmail 郵件，請參閱「傳送郵件」。