gmail

func (*Client) CreateDraft ¶ added in v1.98.0

func (c *Client) CreateDraft(ctx context.Context, userId string, d *draft.Draft, options ...fetch_config.Option) (*draft.Draft, error)

CreateDraft saves a message as a draft. The message's Raw is a base64url-encoded RFC 5322 message, as Send takes; a ThreadId puts the draft in that thread, which Gmail does only when the message's headers say it is a reply in it too. Requires the gmail.compose scope (or wider).

func (*Client) CreateFilter ¶

func (c *Client) CreateFilter(ctx context.Context, userId string, f *filter.Filter, options ...fetch_config.Option) (*filter.Filter, error)

CreateFilter creates a filter for the given user.

func (*Client) CreateForwardingAddress ¶ added in v1.75.0

func (c *Client) CreateForwardingAddress(
	ctx context.Context,
	userId string,
	f *forwarding_address.ForwardingAddress,
	options ...fetch_config.Option,
) (*forwarding_address.ForwardingAddress, error)

CreateForwardingAddress registers a forwarding address for the given user. An address outside the user's domain comes back pending, and Gmail mails it a confirmation that someone there has to act on.

func (*Client) CreateLabel ¶ added in v1.61.0

func (c *Client) CreateLabel(
	ctx context.Context,
	userId string,
	l *label.Label,
	options ...fetch_config.Option,
) (*label.Label, error)

CreateLabel adds a label to the mailbox and returns it with its id.

Creating one that already exists is answered 409 by Gmail rather than returning the existing label, so a caller that wants "ensure it is there" lists first.

func (*Client) CreateSendAs ¶

func (c *Client) CreateSendAs(ctx context.Context, userId string, s *send_as.SendAs, options ...fetch_config.Option) (*send_as.SendAs, error)

CreateSendAs creates a custom "from" send-as alias for the given user.

func (*Client) DeleteDraft ¶ added in v1.98.0

func (c *Client) DeleteDraft(ctx context.Context, userId string, draftId string, options ...fetch_config.Option) error

DeleteDraft deletes a draft outright; it does not go to the trash. Requires the gmail.compose scope (or wider).

func (*Client) DeleteFilter ¶

func (c *Client) DeleteFilter(ctx context.Context, userId string, filterId string, options ...fetch_config.Option) error

DeleteFilter deletes a filter identified by filterId for the given user.

func (*Client) DeleteForwardingAddress ¶ added in v1.75.0

func (c *Client) DeleteForwardingAddress(
	ctx context.Context,
	userId string,
	forwardingEmail string,
	options ...fetch_config.Option,
) error

DeleteForwardingAddress deletes the forwarding address forwardingEmail for the given user, and revokes its verification.

func (*Client) DeleteLabel ¶ added in v1.98.0

func (c *Client) DeleteLabel(ctx context.Context, userId string, labelId string, options ...fetch_config.Option) error

DeleteLabel deletes a label and takes it off every message carrying it; the messages themselves stay. A system label is refused by Gmail.

func (*Client) DeleteSendAs ¶

func (c *Client) DeleteSendAs(ctx context.Context, userId string, sendAsEmail string, options ...fetch_config.Option) error

DeleteSendAs deletes a send-as alias identified by sendAsEmail for the given user.

func (*Client) GetAttachment ¶ added in v1.98.0

func (c *Client) GetAttachment(
	ctx context.Context,
	userId string,
	messageId string,
	attachmentId string,
	options ...fetch_config.Option,
) (*body.Body, error)

GetAttachment retrieves the content of one of a message's attachments.

A message read in full names its attachments by an id in each part's body and leaves their content out, which is fetched here. The content comes back in Data, base64url-encoded as every body in the API is. The id is not stable: two reads of the same message may name the same attachment by different ids, so it is to be used from the read that gave it, not stored.

func (*Client) GetDraft ¶ added in v1.98.0

func (c *Client) GetDraft(
	ctx context.Context,
	userId string,
	draftId string,
	options ...get_message_config.Option,
) (*draft.Draft, error)

GetDraft retrieves a draft and its message, in the format the options ask for.

func (*Client) GetFilter ¶

func (c *Client) GetFilter(ctx context.Context, userId string, filterId string, options ...fetch_config.Option) (*filter.Filter, error)

GetFilter retrieves a filter identified by filterId for the given user.

func (*Client) GetForwardingAddress ¶ added in v1.75.0

func (c *Client) GetForwardingAddress(
	ctx context.Context,
	userId string,
	forwardingEmail string,
	options ...fetch_config.Option,
) (*forwarding_address.ForwardingAddress, error)

GetForwardingAddress retrieves the forwarding address forwardingEmail for the given user.

func (*Client) GetLabel ¶ added in v1.98.0

func (c *Client) GetLabel(ctx context.Context, userId string, labelId string, options ...fetch_config.Option) (*label.Label, error)

GetLabel retrieves one label, with the counts of the messages and threads carrying it, which a listing of every label leaves out.

func (*Client) GetMessage ¶

func (c *Client) GetMessage(ctx context.Context, userId string, messageId string, options ...get_message_config.Option) (*message.Message, error)

GetMessage retrieves a message identified by messageId for the given user.

func (*Client) GetProfile ¶ added in v1.62.0

func (c *Client) GetProfile(ctx context.Context, userId string, options ...fetch_config.Option) (*profile.Profile, error)

GetProfile retrieves the mailbox's profile, which is how to ask where its history stands now.

That is the one question a history listing cannot answer for the caller who needs it most: reading history requires a start id still inside Gmail's window, and a caller whose stored cursor has fallen outside it is told only that it is gone. This is where such a caller starts again from.

func (*Client) GetSendAs ¶

func (c *Client) GetSendAs(ctx context.Context, userId string, sendAsEmail string, options ...fetch_config.Option) (*send_as.SendAs, error)

GetSendAs retrieves a send-as alias identified by sendAsEmail for the given user.

func (*Client) GetThread ¶ added in v1.98.0

func (c *Client) GetThread(
	ctx context.Context,
	userId string,
	threadId string,
	options ...get_message_config.Option,
) (*thread.Thread, error)

GetThread retrieves a thread and its messages.

It takes a message read's options, since a thread is read message by message in the format asked for; the raw format is the one a thread refuses.

func (*Client) ListDraftsPage ¶ added in v1.98.0

func (c *Client) ListDraftsPage(
	ctx context.Context,
	userId string,
	options ...list_drafts_config.Option,
) (*page.Page[*draft.Draft], error)

ListDraftsPage retrieves one page of the user's drafts, beginning at the options' page token. Each carries its id and its message's ids; GetDraft reads one.

func (*Client) ListFilters ¶

func (c *Client) ListFilters(ctx context.Context, userId string, options ...fetch_config.Option) ([]*filter.Filter, error)

ListFilters retrieves all filters for the given user.

func (*Client) ListForwardingAddresses ¶ added in v1.75.0

func (c *Client) ListForwardingAddresses(
	ctx context.Context,
	userId string,
	options ...fetch_config.Option,
) ([]*forwarding_address.ForwardingAddress, error)

ListForwardingAddresses retrieves all forwarding addresses for the given user.

func (*Client) ListHistory ¶

func (c *Client) ListHistory(ctx context.Context, userId string, startHistoryId string, options ...list_history_config.Option) ([]*history.Record, error)

ListHistory retrieves all history records for the given user after the specified startHistoryId.

func (*Client) ListLabels ¶ added in v1.61.0

func (c *Client) ListLabels(ctx context.Context, userId string, options ...fetch_config.Option) ([]*label.Label, error)

ListLabels returns every label in the mailbox.

A label is applied by id, and a user-created label's id is opaque, so this is how a caller finds the id of a label it knows only by name.

func (*Client) ListMessages ¶

func (c *Client) ListMessages(ctx context.Context, userId string, options ...list_messages_config.Option) ([]*message.Message, error)

ListMessages retrieves all messages for the given user matching the optional query, following the paging to the end. Only message IDs and thread IDs are populated; use GetMessage to retrieve the full message.

Spam and trash are left out unless WithIncludeSpamTrash asks for them, as Gmail leaves them out: a caller taking stock of everything a mailbox holds wants them, and one reading the inbox does not.

func (*Client) ListMessagesPage ¶ added in v1.98.0

func (c *Client) ListMessagesPage(
	ctx context.Context,
	userId string,
	options ...list_messages_config.Option,
) (*page.Page[*message.Message], error)

ListMessagesPage retrieves one page of the messages matching the options, beginning at the options' page token.

It is ListMessages for a caller that shows what it finds rather than taking stock of it: a search of a large mailbox matches more than anyone reads, and following the paging to the end would fetch all of it to show the first few.

func (*Client) ListThreadsPage ¶ added in v1.98.0

func (c *Client) ListThreadsPage(
	ctx context.Context,
	userId string,
	options ...list_messages_config.Option,
) (*page.Page[*thread.Thread], error)

ListThreadsPage retrieves one page of the threads matching the options, beginning at the options' page token.

A thread listing takes the parameters a message listing does, which is why it is given the same options. What it returns carries each thread's id and snippet and no messages: GetThread reads one.

func (*Client) Modify ¶ added in v1.61.0

func (c *Client) Modify(
	ctx context.Context,
	userId string,
	messageId string,
	request *modify_request.Request,
	options ...fetch_config.Option,
) (*message.Message, error)

Modify changes which labels a message carries. Requires the gmail.modify scope (or wider).

It is how a service marks what it has done with a message, which is the one record the mailbox keeps and a database cannot: a database knows what it ingested, and says nothing about what arrived and was never read.

A request naming no label is refused. Gmail accepts it and changes nothing, so the call would succeed while doing none of what the caller meant.

func (*Client) ModifyThread ¶ added in v1.61.0

func (c *Client) ModifyThread(
	ctx context.Context,
	userId string,
	threadId string,
	request *modify_request.Request,
	options ...fetch_config.Option,
) (*thread.Thread, error)

ModifyThread changes which labels every message in a thread carries.

The same call as Modify against the conversation rather than one message, which is what to use when what was decided applies to the exchange and not to a single arrival.

func (*Client) Send ¶

func (c *Client) Send(ctx context.Context, userId string, msg *message.Message, options ...fetch_config.Option) (*message.Message, error)

Send sends the specified message to the recipients in the To, Cc, and Bcc headers. The message should have its Raw field set to a base64url-encoded RFC 2822 email.

func (*Client) SendDraft ¶ added in v1.98.0

func (c *Client) SendDraft(ctx context.Context, userId string, draftId string, options ...fetch_config.Option) (*message.Message, error)

SendDraft sends a saved draft as it stands, and returns the message sent. Requires the gmail.compose scope (or wider).

It names the draft by id alone, so what goes out is what was saved, rather than whatever a caller sends along with the id.

func (*Client) Trash ¶

func (c *Client) Trash(ctx context.Context, userId string, messageId string, options ...fetch_config.Option) (*message.Message, error)

Trash moves the given message to the user's trash. Requires the gmail.modify scope (or wider).

func (*Client) TrashThread ¶ added in v1.98.0

func (c *Client) TrashThread(ctx context.Context, userId string, threadId string, options ...fetch_config.Option) (*thread.Thread, error)

TrashThread moves every message in a thread to the user's trash. Requires the gmail.modify scope (or wider).

func (*Client) Untrash ¶ added in v1.98.0

func (c *Client) Untrash(ctx context.Context, userId string, messageId string, options ...fetch_config.Option) (*message.Message, error)

Untrash takes the given message out of the user's trash. Requires the gmail.modify scope (or wider).

func (*Client) UntrashThread ¶ added in v1.98.0

func (c *Client) UntrashThread(ctx context.Context, userId string, threadId string, options ...fetch_config.Option) (*thread.Thread, error)

UntrashThread takes every message in a thread out of the user's trash. Requires the gmail.modify scope (or wider).

func (*Client) UpdateDraft ¶ added in v1.98.0

func (c *Client) UpdateDraft(
	ctx context.Context,
	userId string,
	draftId string,
	d *draft.Draft,
	options ...fetch_config.Option,
) (*draft.Draft, error)

UpdateDraft replaces a draft's message with the one given, keeping the draft's id. Requires the gmail.compose scope (or wider).

func (*Client) UpdateLabel ¶ added in v1.98.0

func (c *Client) UpdateLabel(
	ctx context.Context,
	userId string,
	labelId string,
	l *label.Label,
	options ...fetch_config.Option,
) (*label.Label, error)

UpdateLabel changes the fields of a label that l sets, leaving the rest; it is how a label is renamed. A system label is refused by Gmail.

func (*Client) UpdateSendAs ¶

func (c *Client) UpdateSendAs(ctx context.Context, userId string, sendAsEmail string, s *send_as.SendAs, options ...fetch_config.Option) (*send_as.SendAs, error)

UpdateSendAs updates a send-as alias identified by sendAsEmail for the given user.

func (*Client) Watch ¶

func (c *Client) Watch(ctx context.Context, userId string, request *watch_request.WatchRequest, options ...fetch_config.Option) (*watch_response.WatchResponse, error)

Watch sets up or renews a push notification watch on the given user's mailbox. Notifications are delivered to the Cloud Pub/Sub topic specified in the request's TopicName.