Java Quickstart

Stay organized with collections Save and categorize content based on your preferences.

Complete the steps described in the rest of this page to create a simple Java command-line application that makes requests to the Gmail API.


To run this quickstart, you need the following prerequisites:

  • Authorization credentials for a desktop application. To learn how to create credentials for a desktop application, refer to Create credentials.

  • A Google account with Gmail enabled.

Step 1: Prepare the project

To prepare the project:

  1. In your working directory, run the following commands to create a new project structure:

    gradle init --type basic
    mkdir -p src/main/java src/main/resources 
  2. Copy the credentials.json file you downloaded as a prerequisite into the newly-created src/main/resources/ directory.

  3. Open the default build.gradle file and replace its contents with the following code:

    apply plugin: 'java'
    apply plugin: 'application'
    mainClassName = 'GmailQuickstart'
    sourceCompatibility = 11
    targetCompatibility = 11
    version = '1.0'
    repositories {
    dependencies {
        implementation ''
        implementation ''
        implementation ''

Step 2: Set up the sample

To set up the sample:

  1. In src/main/java/, create a new Java file with a name that matches the mainClassName value in your build.gradle file.
  2. Include the following code in your new Java file:

    import java.util.Collections;
    import java.util.List;
    /* class to demonstrate use of Gmail list labels API */
    public class GmailQuickstart {
       * Application name.
      private static final String APPLICATION_NAME = "Gmail API Java Quickstart";
       * Global instance of the JSON factory.
      private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
       * Directory to store authorization tokens for this application.
      private static final String TOKENS_DIRECTORY_PATH = "tokens";
       * Global instance of the scopes required by this quickstart.
       * If modifying these scopes, delete your previously saved tokens/ folder.
      private static final List<String> SCOPES = Collections.singletonList(GmailScopes.GMAIL_LABELS);
      private static final String CREDENTIALS_FILE_PATH = "/credentials.json";
       * Creates an authorized Credential object.
       * @param HTTP_TRANSPORT The network HTTP Transport.
       * @return An authorized Credential object.
       * @throws IOException If the credentials.json file cannot be found.
      private static Credential getCredentials(final NetHttpTransport HTTP_TRANSPORT)
          throws IOException {
        // Load client secrets.
        InputStream in = GmailQuickstart.class.getResourceAsStream(CREDENTIALS_FILE_PATH);
        if (in == null) {
          throw new FileNotFoundException("Resource not found: " + CREDENTIALS_FILE_PATH);
        GoogleClientSecrets clientSecrets =
            GoogleClientSecrets.load(JSON_FACTORY, new InputStreamReader(in));
        // Build flow and trigger user authorization request.
        GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder(
            HTTP_TRANSPORT, JSON_FACTORY, clientSecrets, SCOPES)
            .setDataStoreFactory(new FileDataStoreFactory(new
        LocalServerReceiver receiver = new LocalServerReceiver.Builder().setPort(8888).build();
        Credential credential = new AuthorizationCodeInstalledApp(flow, receiver).authorize("user");
        //returns an authorized Credential object.
        return credential;
      public static void main(String... args) throws IOException, GeneralSecurityException {
        // Build a new authorized API client service.
        final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
        Gmail service = new Gmail.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
        // Print the labels in the user's account.
        String user = "me";
        ListLabelsResponse listResponse = service.users().labels().list(user).execute();
        List<Label> labels = listResponse.getLabels();
        if (labels.isEmpty()) {
          System.out.println("No labels found.");
        } else {
          for (Label label : labels) {
            System.out.printf("- %s\n", label.getName());

Step 3: Run the sample

  1. Run the sample using the following command:

    gradle run
  2. If this is your first time running the sample, authorize the app to access your data:

    1. In the window that appears, sign in to the Google account that you wish to use for authorization.

    2. Click Accept.

The sample executes.

If you have problems, refer to the Troubleshoot the sample section.

Troubleshoot the sample

This section describes a common issue that you can encounter while attempting to run this quickstart.

This app isn't verified

If the OAuth consent screen displays the warning "This app isn't verified," your app is requesting scopes that provide access to sensitive user data. If your application uses sensitive scopes, your app must go through the verification process to remove that warning and other limitations. During the development phase, you can continue past this warning by selecting Advanced > Go to {Project Name} (unsafe).

File not found error for credentials.json

When running the sample, you might receive a file not found or no such file error regarding credentials.json.

This error occurs when you have not authorized the desktop application credentials as detailed in the Prerequisites section above. To learn how to create credentials for a desktop application, go to Create credentials.

Once you create the credentials, make sure the downloaded JSON file is saved as credentials.json. Then move the file to your working directory with the rest of the sample quickstart code.

Further reading

For further information on the APIs used in this quickstart, refer to the following: