Gmail for PowerShell

A PowerShell module for managing your Gmail, with all the tools you'll need. Search, read and send emails, archive, mark as read/unread, delete emails, and manage labels.

This module is no longer maintained.

Install

If you have PsGet installed you can simply execute:

Install-Module Gmail.ps

Or install it manually:

git clone https://github.com/nikoblag/Gmail.ps.git
cd Gmail.ps
.\install.ps1

Features

Read emails
Search emails
(Update) emails: label, archive, delete, mark as read/unread/spam, star
Manage labels
Move between labels/mailboxes
Automatic authentication, using the Windows Credential Manager

Get help

List of all available commands
```
Get-Command -Module Gmail.ps
```
Help for a specific command.
```
Get-Help <command>
```

Commands

For more detailed information about a command use the help.

New-GmailSession

Opens a connection to a Gmail account using the specified credentials and creates a new session. If a generic credential is created using the Windows Credential Manager (address: Gmail.ps:default), a session is automatically created using the stored credentials each time the cmdlet is executed without a -Credential parameter.

New-GmailSession [[-Credential] <PSCredential>] [<CommonParameters>]

Parameters

Name	Pipeline input	Default
`-Credential`	No	`Get-StoredCredential Gmail.ps:default` or `Get-Credential`

Examples

Authenticating a Gmail session using the stored credential in the Gmail.ps:default entry. If there is no credential stored a prompt for username and password will be displayed.
```
$gmail = New-GmailSession
# play with your gmail...
```

Remove-GmailSession

Closes the connection to Gmail and destroys the session.

Remove-GmailSession [-Session] <ImapClient> [<CommonParameters>]

Parameters

Name	Pipeline input
`-Session`	ByValue, ByPropertyName

Examples

Closing an already opened connection to a Gmail account:
```
$gmail | Remove-GmailSession
```

Invoke-GmailSession

Creates a new Gmail session and passes it to a script block. Once the block is executed, the session is automatically closed.

Invoke-GmailSession [[-Credential] <PSCredential>] [-ScriptBlock] <ScriptBlock> [<CommonParameters>]

Parameters

Name	Pipeline input	Default
`-Credential`	No	`Get-StoredCredential Gmail.ps:default` or `Get-Credential`
`-ScriptBlock`	No

Examples

Creates a Gmail session, returns the number of messages in the Inbox and then closes the session. The automatically created session can be accessed inside the script block via the $args variable.
```
Invoke-GmailSession -ScriptBlock {
    $args | Count-Message
}
```
Creates a Gmail session, returns all the labels used in that account and then closes the session. The automatically created session can be accessed inside the script block via the $gmail variable.
```
Invoke-GmailSession -ScriptBlock {
    param($gmail)
    $gmail | Get-Label
}
```

Get-GmailSession

Returns a list of all opened Gmail sessions.

Get-GmailSession

Clear-GmailSession

Closes all opened Gmail sessions.

Clear-GmailSession

Get-Mailbox

Returns the Inbox if no parameters are specified, an existing Label or one of the default Gmail folders (All Mail, Starred, Drafts, Important, Sent Mail, Spam).

Alias: Select-Mailbox

Get-Mailbox -Session <ImapClient> [[-Name] <String>] [<CommonParameters>]

Get-Mailbox -Session <ImapClient> [-Label <String>] [<CommonParameters>]

Parameters

Name	Pipeline input	Default (List of possible values)
`-Session`	ByValue, ByPropertyName
`-Name`	ByPropertyName	`Inbox` (`All Mail`, `Starred`, `Drafts`, `Important`, `Sent Mail`, `Spam`)
`-Label`	ByPropertyName

Examples

Get the unread messages in the inbox:

$inbox = $gmail | Get-Mailbox
$inbox | Get-Message -Unread

Get the messages marked as Important by Gmail:

$gmail | Get-Mailbox "Important" | Get-Message

Get-Message

Returns a (filtered) list of the messages inside a selected mailbox (see Get-Mailbox). The returned messages will have their body and attachments downloaded only if the -Prefetch parameter is specified.

Every listed message has a set of flags indicating the message's status and properties.

Flag	Meaning
`u`	Is unread
`f`	Is fetched
`i`	Is important
`s`	Is starred
`a`	Has attachment

Any flag may be unset. An unset flag is the equivalent of "is not" and is represented as a - character. --i-a means the message is not Unread, is not Fetched, is Important, is not Starred and has atleast one attachment.

Supports automatic name completion for the existing labels.

Alias: Filter-Message

Get-Message [-Session] <ImapClient>
			[[-From] <String>] [[-To] <String>]
			[[-On] <DateTime>] [[-After] <DateTime>] [[-Before] <DateTime>]
			[[-Cc] <String>] [[-Bcc] <String>]
			[[-Subject] <String>] [[-Text] <String>] [[-Body] <String>]
			[[-Label] <String[]>] [[-FileName] <String>] [[-Category] <String>]
			[-Unread ] [-Read ] [-Starred ] [-Unstarred ] [-HasAttachment ]
			[-Answered ] [-Draft ] [-Undraft ] [-Prefetch ] [<CommonParameters>]

Parameters

Name	Pipeline input	Default (List of possible values)
`-Session`	ByValue, ByPropertyName
`-From`	No
`-To`	No
`-On`	No
`-After`	No
`-Before`	No
`-Cc`	No
`-Bcc`	No
`-Subject`	No
`-Text`	No
`-Body`	No
`-Label`	No
`-FileName`	No
`-Category`	No	none (`Primary`, `Personal`, `Social`, `Promotions`, `Updates`, `Forums`)
`-Unread`	No
`-Read`	No
`-Starred`	No
`-Unstarred`	No
`-HasAttachment`	No
`-Answered`	No
`-Draft`	No
`-Undraft`	No
`-Prefetch`	No

Examples

Get the unread messages in the inbox:

$inbox = $gmail | Get-Mailbox
$inbox | Get-Message -Unread

Get the messages marked as Important by Gmail:

$gmail | Get-Mailbox "Important" | Get-Message

Filter with some criteria:

$inbox | Get-Message -After "2011-06-01" -Before "2012-01-01"
$inbox | Get-Message -On "2011-06-01"
$inbox | Get-Message -From "[email protected]"
$inbox | Get-Message -To "[email protected]"

Combine flags and options:

$inbox | Get-Message -Unread -From "[email protected]"

Update-Message

Archives, marks as spam, as read/undead and adds/removes a star from a given message.

Update-Message -Session <ImapClient> -Message <MailMessage> [-Read ] [-Star ] [-Archive ] [-Spam ] [<CommonParameters>]

Update-Message -Session <ImapClient> -Message <MailMessage> [-Read ] [-Unstar ] [-Archive ] [-Spam ] [<CommonParameters>]

Update-Message -Session <ImapClient> -Message <MailMessage> [-Unread ] [-Star ] [-Archive ] [-Spam ] [<CommonParameters>]

Update-Message -Session <ImapClient> -Message <MailMessage> [-Unread ] [-Unstar ] [-Archive ] [-Spam ] [<CommonParameters>]

Parameters

Name	Pipeline input
`-Session`	ByValue, ByPropertyName
`-Message`	ByValue
`-Read`	No
`-Unread`	No
`-Archive`	No
`-Star`	No
`-Unstar`	No
`-Spam`	No

Examples

Each message can be manipulated using block style. Remember that every message in a conversation/thread will come as a separate message.

$messages = $inbox | Get-Message -Unread | Select-Object -Last 10
foreach ($msg in $messages) {
    $msg | Update-Message -Read # you can use -Unread, -Spam, -Star, -Unstar, -Archive too
}

Receive-Message

Fetches the whole message from the server (including the body and the attachments).

Receive-Message [-Session] <ImapClient> [-Message] <MailMessage> [<CommonParameters>]

Parameters

Name	Pipeline input
`-Session`	ByValue, ByPropertyName
`-Message`	ByValue

Examples

To read the actual body of a message you have to first fetch it from the Gmail servers:

$msg = $inbox | Get-Message -From "[email protected]" | Receive-Message
$msg.Body # returns the body of the message

Move-Message

Moves a message to a different mailbox or label.

Supports automatic name completion for the existing labels.

Move-Message -Session <ImapClient> -Message <MailMessage> [-Mailbox] <String> [<CommonParameters>]

Move-Message -Session <ImapClient> -Message <MailMessage> -Label <String> [<CommonParameters>]

Parameters

Name	Pipeline input
`-Session`	ByValue, ByPropertyName
`-Message`	ByValue
`-Mailbox`	No
`-Label`	No

Examples

Move the message to the All Mail mailbox:
```
$msg | Move-Message "All Mail"
```
Move the message to the Test label:
```
$msg | Move-Message -Label "Test"
```

Remove-Message

Sends a message to the Gmail's Trash folder.

Remove-Message [-Session] <ImapClient> [-Message] <MailMessage> [<CommonParameters>]

Parameters

Name	Pipeline input
`-Session`	ByValue, ByPropertyName
`-Message`	ByValue

Examples

Delete all emails from X:

$inbox | Get-Message -From "[email protected]" | Remove-Message

Measure-Message

Returns the number of messages in a mailbox (supports labels too).

Alias: Count-Message

Measure-Message [-Session] <ImapClient> [<CommonParameters>]

Parameters

Name	Pipeline input
`-Session`	ByValue, ByPropertyName

Examples

Count the messages in the inbox:
```
$inbox | Measure-Message
```

Count the important messages:

$gmail | Get-Mailbox "Important" | Measure-Message

Note that Measure-Message will return the number of all messages in the selected mailbox, not the number of the returned messages (if any). To count the returned messages, use Measure-Object. For example if we have 2 unread and 98 read messages in the Important mailbox:

# returns 100, the number of messages in `Important`
$gmail | Get-Mailbox "Important" | Get-Message -Unread | Measure-Message

# returns 2, the number of unread messages in `Important`
$gmail | Get-Mailbox "Important" | Get-Message -Unread | Measure-Object

Get-Conversation

Returns a list of messages that are part of a conversation.

Alias: Get-Thread

Get-Conversation [-Session] <ImapClient> [-Message] <MailMessage> [-Prefetch] [<CommonParameters>]

Parameters

Name	Pipeline input
`-Session`	ByValue, ByPropertyName
`-Message`	ByValue
`-Prefetch`	No

Examples

Search the Inbox based on the message returned by Get-Message, and return all messages that are part of that conversaton and are in the Inbox:
```
$gmail | Get-Mailbox "Inbox" | Get-Message -From "[email protected]" | Get-Conversaion
```
Search "All Mail" based on the message returned by Get-Message, and return all messages that are part of that conversaton:
```
$gmail | Get-Mailbox "All Mail" | Get-Message -From "[email protected]" | Get-Conversaion
```

Save-Attachment

Downloads the attachments of a message to a local folder.

Save-Attachment [-Message <MailMessage>] [-Path] <String[]> [-PassThru ] [<CommonParameters>]

Save-Attachment [-Message <MailMessage>] -LiteralPath <String[]> [-PassThru ] [<CommonParameters>]

Parameters

Name	Pipeline input
`-Message`	ByValue
`-Path`	No
`-LiteralPath`	No
`-PassThru`	No

Examples

Save all attachments in the "Important" label to a local folder. Note that without the -Prefetch parameter, no attachments will be downloaded:
```
$gmail | Get-Mailbox -Label "Important" | Get-Message -Prefetch | Save-Attachment $folder
```

Save just the first attachment from the newest unread email:

$msg = $inbox | Get-Message -Unread -HasAttachment | Select-Object -Last 1
$fetchedMsg = $msg | Receive-Message # or use -Prefetch on Get-Message above
$fetchedMsg.Attachments[0].Save($location)

Get-Label

Returns the labels applied to a message or all labels that exist.

Get-Label -Session <ImapClient> [-Message <MailMessage>] [[-Like] <String>] [-All ] [<CommonParameters>]

Parameters

Name (Alias)	Pipeline input
`-Session`	ByValue, ByPropertyName
`-Message`	ByValue
`-Like` (`-Name`)	No
`-All`	No

Examples

Get all labels applied to a message:
```
$msg | Get-Label
```
Get a list of the defined labels:
```
$gmail | Get-Label
```

Check if a label exists:

$gmail | Get-Label -Name "SomeLabel" # returns null if the label doesn't exist

New-Label

Creates a new label.

New-Label [-Name] <String[]> -Session <ImapClient> [<CommonParameters>]

Parameters

Name	Pipeline input
`-Name`	No
`-Session`	ByValue, ByPropertyName

Set-Label

Applies a label to a message.

Supports automatic name completion for the existing labels.

Alias: Add-Label

Set-Label -Session <ImapClient> -Message <MailMessage> [-Name] <String[]> [-Force ] [<CommonParameters>]

Parameters

Name	Pipeline input
`-Session`	ByValue, ByPropertyName
`-Message`	ByValue
`-Name`	No
`-Force`	No

Examples

Apply a single or multiple labels:

$msg | Set-Label "Important"
$msg | Set-Label "Important","Banking"

The example above will raise error if one of the specified labels doesn't exist. To avoid that, label creation can be forced:
```
$msg | Set-Label "Important","Banking" -Force
```

Remove-Label

Removes a label from a message or deletes the label from the account.

Supports automatic name completion for the existing labels.

Remove-Label [-Name] <String[]> -Session <ImapClient> [-Message <MailMessage>] [<CommonParameters>]

Parameters

Name	Pipeline input
`-Name`	No
`-Session`	ByValue, ByPropertyName
`-Message`	ByValue

Roadmap

Write tests
Send mail via Google's SMTP servers
Backup/restore all messages and labels

History

Check Release list.

Author

Nikolay Blagoev [https://github.com/nikoblag]

Third Party Libraries

Contributing

Fork it.
Create a branch (git checkout -b my_feature)
Commit your changes (git commit -am "Added Feature")
Push to the branch (git push origin my_feature)
Open a Pull Request
Enjoy an ice cream and wait

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
FormatData		FormatData
AE.Net.Mail.dll		AE.Net.Mail.dll
Gmail.ps.psd1		Gmail.ps.psd1
Gmail.ps.psm1		Gmail.ps.psm1
LICENSE		LICENSE
README.md		README.md
install.ps1		install.ps1

License

brendan-mccoy/Gmail.ps

Folders and files

Latest commit

History

Repository files navigation

Gmail for PowerShell

Table of contents

Install

Features

Get help

Commands

New-GmailSession

Parameters

Examples

Remove-GmailSession

Parameters

Examples

Invoke-GmailSession

Parameters

Examples

Get-GmailSession

Clear-GmailSession

Get-Mailbox

Parameters

Examples

Get-Message

Parameters

Examples

Update-Message

Parameters

Examples

Receive-Message

Parameters

Examples

Move-Message

Parameters

Examples

Remove-Message

Parameters

Examples

Measure-Message

Parameters

Examples

Get-Conversation

Parameters

Examples

Save-Attachment

Parameters

Examples

Get-Label

Parameters

Examples

New-Label

Parameters

Set-Label

Parameters

Examples

Remove-Label

Parameters

Roadmap

History

Author

Third Party Libraries

Contributing

License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages