Users.drafts: send

Sends the specified, existing draft to the recipients in the To, Cc, and Bcc headers. Try it now or see an example.

This method supports an /upload URI and accepts uploaded media with the following characteristics:

  • Maximum file size: 35MB
  • Accepted Media MIME types: message/rfc822

Request

HTTP request

This method provides media upload functionality through two separate URIs. For more details, see the document on media upload.

  • Upload URI, for media upload requests: 
    POST https://www.googleapis.com/upload/gmail/v1/users/userId/drafts/send
  • Metadata URI, for metadata-only requests: 
    POST https://www.googleapis.com/gmail/v1/users/userId/drafts/send

Parameters

Parameter name Value Description
Path parameters
userId string The user's email address. The special value me can be used to indicate the authenticated user.
Required query parameters
uploadType string The type of upload request to the /upload URI. Acceptable values are:
  • media - Simple upload. Upload the media only, without any metadata.
  • multipart - Multipart upload. Upload both the media and its metadata, in a single request.
  • resumable - Resumable upload. Upload the file in a resumable fashion, using a series of at least two requests where the first request includes the metadata.

Authorization

This request requires authorization with at least one of the following scopes:

Scope
https://mail.google.com/
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.compose

For more information, see the authentication and authorization page.

Request body

In the request body, supply a Users.drafts resource with the following properties as the metadata. For more information, see the document on media upload.

Property name Value Description Notes
Required Properties
id string The immutable ID of the draft.

Response

If successful, this method returns a response body with the following structure:

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "internalDate": long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}
Property name Value Description Notes
id string The immutable ID of the message.
threadId string The ID of the thread the message belongs to. To add a message or draft to a thread, the following criteria must be met:
  1. The requested threadId must be specified on the Message or Draft.Message you supply with your request.
  2. The References and In-Reply-To headers must be set in compliance with the RFC 2822 standard.
  3. The Subject headers must match.
 writable
labelIds[] list List of IDs of labels applied to this message. writable
snippet string A short part of the message text.
historyId unsigned long The ID of the last history record that modified this message.
payload nested object The parsed email structure in the message parts.
payload.partId string The immutable ID of the message part.
payload.mimeType string The MIME type of the message part.
payload.filename string The filename of the attachment. Only present if this message part represents an attachment.
payload.headers[] list List of headers on this message part. For the top-level message part, representing the entire message payload, it will contain the standard RFC 2822 email headers such as To, From, and Subject.
payload.headers[].name string The name of the header before the : separator. For example, To.
payload.headers[].value string The value of the header after the : separator. For example, someuser@example.com.
payload.body nested object The message part body for this part, which may be empty for container MIME message parts.
payload.parts[] list The child MIME message parts of this part. This only applies to container MIME message parts, for example multipart/*. For non- container MIME message part types, such as text/plain, this field is empty. For more information, see RFC 1521.
sizeEstimate integer Estimated size in bytes of the message.
raw bytes The entire email message in an RFC 2822 formatted and base64url encoded string. Returned in messages.get and drafts.get responses when the format=RAW parameter is supplied. writable
internalDate long The internal message creation timestamp (epoch ms), which determines ordering in the inbox. For normal SMTP-received email, this represents the time the message was originally accepted by Google, which is more reliable than the Date header. However, for API-migrated mail, it can be configured by client to be based on the Date header.

Examples

Note: The code examples available for this method do not represent all supported programming languages (see the client libraries page for a list of supported languages).

Java

Uses the Java client library.

import com.google.api.services.gmail.Gmail;
import com.google.api.services.gmail.model.Draft;
import com.google.api.services.gmail.model.Message;

import java.io.IOException;

// ...

public class MyClass {

  // ...

  /**
   * Send an existing draft to its set recipients.
   *
   * @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 draftId ID of Draft to be sent.
   * @throws java.io.IOException
   */
  public static void sendDraft(Gmail service, String userId, String draftId) throws IOException {
      Draft draft = new Draft();
      draft.setId(draftId);

      // To update the Draft before sending, set a new Message on the Draft before sending.

      Message message = service.users().drafts().send(userId, draft).execute();
      System.out.println("Draft with ID: " + draftId + " sent successfully.");
      System.out.println("Draft sent as Message with ID: " + message.getId());
  }

  // ...

}

Try it!

Note: APIs Explorer currently supports metadata requests only.

Use the APIs Explorer below to call this method on live data and see the response.