/ 
Google-RestApi-2.1.0
River stage zero No dependents
/ Google::RestApi::GmailApi1

NAME

Google::RestApi::GmailApi1 - API to Google Gmail API V1.

SYNOPSIS

Basic Setup

use Google::RestApi;
use Google::RestApi::GmailApi1;

# Create the REST API instance
my $rest_api = Google::RestApi->new(
  config_file => '/path/to/config.yaml',
);

# Create the Gmail API instance
my $gmail_api = Google::RestApi::GmailApi1->new(api => $rest_api);

Profile and Labels

# Get user profile
my $profile = $gmail_api->profile();

# List all labels
my @labels = $gmail_api->labels();

# Create a label
my $label = $gmail_api->label()->create(name => 'My Label');

# Delete a label
$label->delete();

Messages

# List messages
my @messages = $gmail_api->messages();

# Send a message
my $msg = $gmail_api->send_message(
  to      => 'recipient@example.com',
  subject => 'Hello',
  body    => 'Message body',
);

# Get a specific message
my $message = $gmail_api->message(id => 'msg_id');
my $details = $message->get();

# Modify message labels
$message->modify(
  add_label_ids    => ['STARRED'],
  remove_label_ids => ['UNREAD'],
);

# Trash/untrash/delete
$message->trash();
$message->untrash();
$message->delete();

Threads

# List threads
my @threads = $gmail_api->threads();

# Get a thread
my $thread = $gmail_api->thread(id => 'thread_id');
my $details = $thread->get();

Drafts

# Create a draft
my $draft = $gmail_api->draft()->create(
  to      => 'recipient@example.com',
  subject => 'Draft subject',
  body    => 'Draft body',
);

# Send a draft
$draft->send();

Batch Operations

# Batch modify messages
$gmail_api->batch_modify_messages(
  ids              => ['msg1', 'msg2'],
  add_label_ids    => ['STARRED'],
  remove_label_ids => ['UNREAD'],
);

# Batch delete messages
$gmail_api->batch_delete_messages(ids => ['msg1', 'msg2']);

DESCRIPTION

Google::RestApi::GmailApi1 provides a Perl interface to the Google Gmail API V1. It enables email management including:

  • Message operations (send, read, modify labels, trash, delete)

  • Thread management (list, get, modify, trash, delete)

  • Draft management (create, update, send, delete)

  • Label management (create, get, update, delete)

  • Batch operations (batch modify/delete messages)

  • Attachment retrieval

It is assumed that you are familiar with the Google Gmail API: https://developers.google.com/gmail/api/reference/rest

Architecture

The API uses a hierarchical object model where child objects delegate API calls to their parent:

GmailApi1 (top-level)
  |-- message(id => ...)       -> Message
  |     |-- attachment(id => ...) -> Attachment
  |-- thread(id => ...)        -> Thread
  |-- draft(id => ...)         -> Draft
  |-- label(id => ...)         -> Label

Each object provides CRUD operations appropriate to its resource type.

NAVIGATION

SUBROUTINES

new(%args)

Creates a new GmailApi1 instance.

my $gmail_api = Google::RestApi::GmailApi1->new(api => $rest_api);

%args consists of:

  • api Google::RestApi: Required. A configured RestApi instance.

  • user_id <string>: Optional. The user ID (default 'me' for authenticated user).

  • endpoint <string>: Optional. Override the default Gmail API endpoint.

api(%args)

Low-level method to make API calls. You would not normally call this directly unless making a Google API call not currently supported by this framework.

%args consists of:

  • uri <string>: Path segments to append to the Gmail endpoint.

  • %args: Additional arguments passed to Google::RestApi's api() (content, params, method, etc).

Returns the response hash from the Google API.

message(%args)

Returns a Message object for the given message ID.

my $msg = $gmail_api->message(id => 'msg_id');

thread(%args)

Returns a Thread object for the given thread ID.

my $thread = $gmail_api->thread(id => 'thread_id');

draft(%args)

Returns a Draft object for the given draft ID.

my $draft = $gmail_api->draft(id => 'draft_id');

label(%args)

Returns a Label object for the given label ID.

my $label = $gmail_api->label(id => 'label_id');

profile()

Gets the authenticated user's Gmail profile.

my $profile = $gmail_api->profile();

Returns a hashref with emailAddress, messagesTotal, threadsTotal, historyId.

messages(%args)

Lists messages in the user's mailbox.

my @messages = $gmail_api->messages();
my @filtered = $gmail_api->messages(params => { q => 'from:user@example.com' });
my @paged = $gmail_api->messages(max_pages => 2, params => { maxResults => 10 });

%args consists of:

  • max_pages <int>: Optional. Maximum number of pages to fetch (default 1). Set to 0 for unlimited.

  • page_callback <coderef>: Optional. See "PAGE CALLBACKS" in Google::RestApi.

  • params <hashref>: Optional. Query parameters (q, maxResults, labelIds, etc).

Returns a list of message hashrefs with id and threadId.

threads(%args)

Lists threads in the user's mailbox.

my @threads = $gmail_api->threads();
my @paged = $gmail_api->threads(max_pages => 2, params => { maxResults => 10 });

%args consists of:

  • max_pages <int>: Optional. Maximum number of pages to fetch (default 1). Set to 0 for unlimited.

  • page_callback <coderef>: Optional. See "PAGE CALLBACKS" in Google::RestApi.

  • params <hashref>: Optional. Query parameters (q, maxResults, etc).

Returns a list of thread hashrefs with id and snippet.

labels()

Lists all labels in the user's mailbox.

my @labels = $gmail_api->labels();

Returns a list of label hashrefs.

send_message(%args)

Sends an email message.

my $msg = $gmail_api->send_message(
  to      => 'recipient@example.com',
  subject => 'Hello',
  body    => 'Message body',
);

%args consists of:

  • to <string>: Required. Recipient email address.

  • subject <string>: Required. Message subject.

  • body <string>: Required. Message body.

  • from <string>: Optional. Sender address.

  • cc <string>: Optional. CC recipients.

  • bcc <string>: Optional. BCC recipients.

  • content_type <string>: Optional. MIME content type (default 'text/plain').

Returns a Message object for the sent message.

send_raw_message(raw => $base64url)

Sends a pre-encoded raw message.

batch_modify_messages(%args)

Batch modifies labels on multiple messages.

$gmail_api->batch_modify_messages(
  ids              => ['msg1', 'msg2'],
  add_label_ids    => ['STARRED'],
  remove_label_ids => ['UNREAD'],
);

batch_delete_messages(ids => \@ids)

Permanently batch deletes multiple messages.

rest_api()

Returns the underlying Google::RestApi instance.

SEE ALSO

AUTHORS

  • Robin Murray mvsjes@cpan.org

COPYRIGHT

Copyright (c) 2019-2026 Robin Murray. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.