GoogleDriveManagement/wiki/Users-Gmail-Messages-Threads.md

Users - Gmail - Messages/Threads

• Notes
• API documentation
• Query documentation
• Definitions
• Subject and label queries
• Draft messages
• Import messages
• Insert messages
• Archive messages
• Export messages/threads
• Forward messages/threads
• Manage messages/threads
• Delete messages by Message-Id
• Display messages/threads
  • Display all messages
  • Display a specific set of messages
  • Display a selected set of messages
  • Choose information to display
    • Display message content
    • Display message counts
    • Display label counts
  • Print only options
  • Show only options
  • Download attachments
  • Upload attachments
  • Display messages sent by delegates for delegator
• User attribute replace <Tag> <UserReplacement> processing

Notes

• Restrict email messages to authorized addresses or domains only
• Block emails between specific user groups

API documentation

• Gmail API - Messages
• Gmail API - Threads
• Gmail API - Drafts
• Gmail API - Import
• Gmail API - Insert
• Groups Migration API - Archive

Query documentation

• Search Messages

The document above shows the following queries in the left column; they don't work, use the query in the right column.

Fails	Works
has:yellow-star	l:^ss_sy
has:blue-star	l:^ss_sb
has:red-star	l:^ss_sr
has:orange-star	l:^ss_so
has:green-star	l:^ss_sg
has:purple-star	l:^ss_sp
has:red-bang	l:^ss_cr
has:yellow-bang	l:^ss_cy
has:blue-info	l:^ss_cb
has:orange-guillemet	l:^ss_co
has:green-check	l:^ss_cg
has:purple-question	l:^ss_cp

This table and other suggestions came from:

• https://www.planetahuevo.es/uso-de-gmail-avanzado-saca-partido-a-tu-gmail/

Definitions

• <UserTypeEntity>
• Command data from Google Docs/Sheets/Storage

<DomainName> ::= <String>(.<String>)+
<EmailAddress> ::= <String>@<DomainName>
<UniqueID> ::= id:<String>
<GroupItem> ::= <EmailAddress>|<UniqueID>|<String>
<LabelName> ::= <String>
<QueryGmail> ::= <String> See: https://support.google.com/mail/answer/7190
<Time> ::=
        <Year>-<Month>-<Day>(<Space>|T)<Hour>:<Minute>:<Second>[.<MilliSeconds>](Z|(+|-(<Hour>:<Minute>))) |
        (+|-)<Number>(m|h|d|w|y) |
        never|
        now|today

<RegularExpression> ::= <String>
        See: https://docs.python.org/3/library/re.html
<REMatchPattern> ::= <RegularExpression>
<RESearchPattern> ::= <RegularExpression>
<RESubstitution> ::= <String>>

<SMTPDateHeader> ::=
        date|
        delivery-date|
        expires|
        expiry-date|
        latest-delivery-time|
        reply-by|
        resent-date
<SMTPHeader> ::=
        accept-language|
        alternate-recipient|
        autoforwarded|
        autosubmitted|
        bcc|
        cc|
        comments|
        content-alternative|
        content-base|
        content-description|
        content-disposition|
        content-duration|
        content-id|
        content-identifier|
        content-language|
        content-location|
        content-md5|
        content-return|
        content-transfer-encoding|
        content-type|
        content-features|
        conversion|
        conversion-with-loss|
        dl-expansion-history|
        deferred-delivery|
        delivered-to|
        discarded-x400-ipms-extensions|
        discarded-x400-mts-extensions|
        disclose-recipients|
        disposition-notification-options|
        disposition-notification-to|
        encoding|
        encrypted|
        from|
        generate-delivery-report|
        importance|
        in-reply-to|
        incomplete-copy|
        keywords|
        language|
        list-archive|
        list-help|
        list-id|
        list-owner|
        list-post|
        list-subscribe|
        list-unsubscribe|
        mime-version|
        message-context|
        message-id|
        message-type|
        obsoletes|
        original-encoded-information-types|
        original-message-id|
        originator-return-address|
        pics-label|
        prevent-nondelivery-report|
        priority|
        received|
        references|
        reply-to|
        resent-bcc|
        resent-cc|
        resent-from|
        resent-message-id|
        resent-reply-to|
        resent-sender|
        resent-to|
        return-path|
        sender|
        sensitivity|
        subject|
        supersedes|
        to|
        x400-content-identifier|
        x400-content-return|
        x400-content-type|
        x400-mts-identifier|
        x400-originator|
        x400-received|
        x400-recipients|
        x400-trace
<SMTPHeaderList> ::= "<SMTPDateHeader|SMTPHeader>(,<SMTPDateHeader|SMTPHeader>)*"

<MessageID> ::= <String>
<MessageIDList> ::= "<MessageID>(,<MessageID>)*"
<MessageIDEntity> ::=
        <MessageIDList> | <FileSelector> | <CSVkmdSelector> | <CSVDataSelector>
        See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items
<ThreadID> ::= <String>
<ThreadIDList> ::= "<ThreadID>(,<ThreadID>)*"
<ThreadIDEntity> ::= <ThreadIDList>|<FileSelector>|<CSVkmdSelector>|<CSVDataSelector>

<StorageBucketName> ::= <String>
<StorageObjectName> ::= <String>
<StorageBucketObjectName> ::=
        https://storage.cloud.google.com/<StorageBucketName>/<StorageObjectName>|
        https://storage.googleapis.com/<StorageBucketName>/<StorageObjectName>|
        gs://<StorageBucketName>/<StorageObjectName>|
        <StorageBucketName>/<StorageObjectName>

<UserGoogleDoc> ::=
        <EmailAddress> <DriveFileIDEntity>|<DriveFileNameEntity>|(<SharedDriveEntity> <SharedDriveFileNameEntity>)

<MessageContent> ::=
        (message|textmessage|htmlmessage <String>)|
        (file|textfile|htmlfile <FileName> [charset <Charset>])|
        (gdoc|ghtml <UserGoogleDoc>)|
        (gcsdoc|gcshtml <StorageBucketObjectName>)|
        (emlfile <FileName> [charset <Charset>]))

<DriveFolderID> ::= <String>
<DriveFolderName> ::= <String>
<SharedDriveID> ::= <String>
<SharedDriveName> ::= <String>

<DriveFileParentAttribute> ::=
        (parentid <DriveFolderID>)|
        (parentname <DriveFolderName>)|
        (anyownerparentname <DriveFolderName>)|
        (teamdriveparentid <DriveFolderID>)|
        (teamdriveparent <SharedDriveName>)|
        (teamdriveparentid <SharedDriveID> teamdriveparentname <DriveFolderName>)|
        (teamdriveparent <SharedDriveName> teamdriveparentname <DriveFolderName>)

Message queries with dates

query <QueryGmail> [querytime<String> <Date>]*

• query "xxx" - xxx is appended to the current query; you can repeat the query argument to build up a longer query.

Use the querytime<String> <Date> option to allow dates, usually relative, to be substituted into the query <QueryGmail> option. The querytime<String> <Date> value replaces the string #querytime<String># in any queries. The characters following querytime can be any combination of lowercase letters and numbers. This is most useful in scripts where you can specify a relative date without having to change the script.

For example, query for messages from moree than 5 years ago:

querytime5years -5y query "before:#querytime5years#"

Subject and label queries

Using a query to select messages by subject or label requires some attention in order to achieve the desired effect.

• https://support.google.com/mail/answer/7190

To select messages with all of the words (word1, word2 and word3) in the subject, regardless of location or order, use:

• query "subject:word1 word2 word3"

To select messages with exactly (word1 word2 word3) in the subject, use:

• query "subject:\"word1 word2 word3\""

To select messages with a label containing &()"|{}/, you have to replace these characters with - in the query. You can also replace with - but it doesn't seem to be required.

• query "label:Foo -Bar-" - Select messages with label Foo (Bar)

You can have GAM do the substitutions for you with the matchlabel <LabelName> option.

• matchlabel "Foo (Bar)" is converted to query "label:Foo -Bar-"

Draft messages

Add a draft message to a user's mailbox.

gam <UserTypeEntity> draft message
        <MessageContent>
        (replace <Tag> <UserReplacement>)*
        (replaceregex <RESearchPattern> <RESubstitution> <Tag> <UserReplacement>)*
        (<SMTPDateHeader> <Time>)* (<SMTPHeader> <String>)* (header <String> <String>)*
        (attach <FileName> [charset <Charset>])*
        (embedimage <FileName> <String>)*

<MessageContent> is the message, there are five ways to specify it:

• message|textmessage|htmlmessage <String> - Use <String> as the message
• file|htmlfile <FileName> [charset <Charset>] - Read the message from <FileName>
• gdoc|ghtml <UserGoogleDoc> - Read the message from <UserGoogleDoc>
• gcsdoc|gcshtml <StorageBucketObjectName> - Read the message from the Google Cloud Storage file <StorageBucketObjectName>
• emlfile <FileName> [charset <Charset>] - Read the message from the EML message file <FileName>. SMTP headers specified in the command will replace those in the message file. The default charset is ascii.

The <SMTPDateHeader> <Time> argument requires <Time> values which will be converted to RFC2822 dates. If you have these headers with values that are not in <Time> format, use the argument header <SMTPDateHeader> <String>.

If you have an SMTP header that is not found in <SMTPDateHeader> or <SMTPHeader>, use header <String> <String>.

The <SMTPHeader> value content-type is not valid for these commands; it will be derived from other arguments.

You can embed images in HTML email messages.

Your HTML message will contain lines like this:

<img src="cid:image1"/>
<img src="cid:image2"/>

Your command line will have: embedimage file1.jpg image1 embedimage file2.jpg image2

Import messages

Import a message into a user's mailbox, with standard email delivery scanning and classification similar to receiving via SMTP.

gam <UserTypeEntity> import message
        <MessageContent>
        (replace <Tag> <UserReplacement>)*
        (replaceregex <RESearchPattern> <RESubstitution> <Tag> <UserReplacement>)*
        (<SMTPDateHeader> <Time>)* (<SMTPHeader> <String>)* (header <String> <String>)*
        (addlabel <LabelName>)* [labels <LabelNameList>]
        (attach <FileName> [charset <Charset>])*
        (embedimage <FileName> <String>)*
        [deleted [<Boolean>]] [checkspam [<Boolean>]] [processforcalendar [<Boolean>]]

<MessageContent> is the message, there are five ways to specify it:

• message|textmessage|htmlmessage <String> - Use <String> as the message
• file|htmlfile <FileName> [charset <Charset>] - Read the message from <FileName>
• gdoc|ghtml <UserGoogleDoc> - Read the message from <UserGoogleDoc>
• gcsdoc|gcshtml <StorageBucketObjectName> - Read the message from the Google Cloud Storage file <StorageBucketObjectName>
• emlfile <FileName> [charset <Charset>] - Read the message from the EML message file <FileName>. SMTP headers specified in the command will replace those in the message. The default chatser is ascii.

When emlfile is not specified:

• If to is not specified, it is set to the user email addresses in <UserTypeEntity>.
• If from is not specified, it is set to the admin user identified in oauth2.txt.

The <SMTPDateHeader> <Time> argument requires <Time> values which will be converted to RFC2822 dates. If you have these headers with values that are not in <Time> format, use the argument header <SMTPDateHeader> <String>.

If you have an SMTP header that is not found in <SMTPDateHeader> or <SMTPHeader>, use header <String> <String>.

The <SMTPHeader> value content-type is not valid for these commands; it will be derived from other arguments.

If no addlabel <LabelName> is specified, the message will be placed in the Inbox.

You can embed images in HTML email messages.

Your HTML message will contain lines like this:

<img src="cid:image1"/>
<img src="cid:image2"/>

Your command line will have: embedimage file1.jpg image1 embedimage file2.jpg image2`

deleted defaults to False, when True: Mark the email as permanently deleted (not TRASH) and only visible in Google Vault to a Vault administrator.

checkspam defaults to False: Ignore the Gmail spam classifier decision and never mark this email as SPAM in the mailbox.

processforcalendar defaults to False, when True: Process calendar invites in the email and add any extracted meetings to the Google Calendar for this user.

Insert messages

Insert a message into a user's mailbox similar to IMAP APPEND, bypassing most scanning and classification.

gam <UserTypeEntity> insert message
        <MessageContent>
        (replace <Tag> <UserReplacement>)*
        (replaceregex <RESearchPattern> <RESubstitution> <Tag> <UserReplacement>)*
        (<SMTPDateHeader> <Time>)* (<SMTPHeader> <String>)* (header <String> <String>)*
        (addlabel <LabelName>)* [labels <LabelNameList>]
        (attach <FileName> [charset <Charset>])*
        (embedimage <FileName> <String>)*
        [deleted [<Boolean>]]

<MessageContent> is the message, there are five ways to specify it:

• message|textmessage|htmlmessage <String> - Use <String> as the message
• file|htmlfile <FileName> [charset <Charset>] - Read the message from <FileName>
• gdoc|ghtml <UserGoogleDoc> - Read the message from <UserGoogleDoc>
• gcsdoc|gcshtml <StorageBucketObjectName> - Read the message from the Google Cloud Storage file <StorageBucketObjectName>
• emlfile <FileName> [charset <Charset>] - Read the message from the EML message file <FileName>. SMTP headers specified in the command will replace those in the message file. The default chatser is ascii.

When emlfile is not specified:

• If to is not specified, it is set to the user email addresses in <UserTypeEntity>.
• If from is not specified, it is set to the admin user identified in oauth2.txt.

The <SMTPDateHeader> <Time> argument requires <Time> values which will be converted to RFC2822 dates. If you have these headers with values that are not in <Time> format, use the argument header <SMTPDateHeader> <String>.

If you have an SMTP header that is not found in <SMTPDateHeader> or <SMTPHeader>, use header <String> <String>.

The <SMTPHeader> value content-type is not valid for these commands; it will be derived from other arguments.

If no addlabel <LabelName> is specified, the message will be placed in the Inbox.

You can embed images in HTML email messages.

Your HTML message will contain lines like this:

<img src="cid:image1"/>
<img src="cid:image2"/>

Your command line will have: embedimage file1.jpg image1 embedimage file2.jpg image2`

deleted defaults to False, when True: Mark the email as permanently deleted (not TRASH) and only visible in Google Vault to a Vault administrator.

Archive messages

gam <UserTypeEntity> archive messages <GroupItem>
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+
         [quick|notquick] [doit] [max_to_archive <Number>])|(ids <MessageIDEntity>)
        [csv [todrive <ToDriveAttribute>*]]

Messages are archived to the group specified by <GroupItem>.

Archive a specific set of messages

• ids <MessageIDEntity> - A list of message ids

Archive a selected set of messages

• ((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+ - Criteria to select messages
• max_to_archive - Limit the number of messages that will be archived; use a value of 0 for no limit
• doit - No messages are archived unless you specify doit. By not specifying doit, you can preview the messages selected to verify that the results match your expectations.

When matchlabel <LabelName> is specified, the following characters are replaced with a - in the generated query.

 &()"|{}/

By default, Gam fetches all matching messages from Google and then processes only max_to_archive of them. To speed up fetching, specify quick and only max_to_archive of the matching messages will be fetched. You must still specify doit to perform the operation.

By default, the command results are displayed as indented keys and values. Use the csv option to display the command results in CSV form.

$ gam user user@domain.com archive messages ids 18e9fc6581b9acab,18e9fc58c5491f4c    
User: user@domain.com, Archive 2 Messages
  User: user@domain.com, Message: 18e9fc6581b9acab, Archived (1/2)
  User: user@domain.com, Message: 18e9fc58c5491f4c, Archived (2/2)
$ gam user user@domain.com archive messages ids 18e9fc6581b9acab,18e9fc58c5491f4c csv
User: user@domain.com, Archive 2 Messages
User,id,action,error
user@domain.com,18e9fc6581b9acab,Archived,
user@domain.com,18e9fc58c5491f4c,Archived,

See below for message selection.

Export messages/threads

Export messages in EML format.

gam <UserTypeEntity> export message|messages
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+ [quick|notquick] [max_to_export <Number>])|(ids <MessageIDEntity>)
        [targetfolder <FilePath>] [targetname <FileName>] [overwrite [<Boolean>]]
gam <UserTypeEntity> export thread|threads
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+ [quick|notquick] [max_to_export <Number>])|(ids <ThreadIDEntity>)
        [targetfolder <FilePath>] [targetname <FileName>] [overwrite [<Boolean>]]

By default, when exporting a message, it is downloaded to the directory specified in gam.cfg/drive_dir.

• targetfolder <FilePath> - Specify an alternate location for the downloaded file.

By default, when exporting a message, the local name is Msg-<MessageID>.

• targetname <FileName> - Specify an alternate name for the downloaded file; #id# will be replaced by <MessageID>.

The strings #email#, #user# and #username# will be replaced by the the user's full email address or just the name portion in targetfolder <FilePath> and targetname <FileName>.

By default, when exporting a message, an existing local file will not be overwritten; a numeric prefix is added to the filename.

• overwrite - Overwite an existing file
• overwrite true - Overwite an existing file
• overwrite false - Do not overwite an existing file; add a numeric prefix and create a new file

See below for message selection.

Forward messages/threads

gam <UserTypeEntity> forward message|messages recipient|to <RecipientEntity>
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+
         [quick|notquick] [doit] [max_to_forward <Number>])|(ids <MessageIDEntity>)
         [subject <String>] [addorigfieldstosubject]
gam <UserTypeEntity> forward thread|threads recipient|to <RecipientEntity>
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+
         [quick|notquick] [doit] [max_to_forward <Number>])|(ids <ThreadIDEntity>)
         [subject <String>] [addorigfieldstosubject]

By default, the message subject has Fwd: prepended; use subject <String> to specify a new subject.

All Cc addresses are removed from the forwarded message.

If addorigfieldstosubject is specified, GAM appends the original from, to and date fields to the message subject.

Fwd: Ross to TestUser (Original From: Ross Scroggs <ross.scroggs@gmail.com> To: testuser@domain.com Date: Thu, 23 Nov 2023 07:01:59 -0800)

See below for message selection.

Manage messages/threads

gam <UserTypeEntity> delete messages|threads
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+
         [quick|notquick] [doit] [max_to_delete <Number>])|(ids <MessageIDEntity>)
        [csv [todrive <ToDriveAttribute>*]]
gam <UserTypeEntity> modify messages|threads
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+
         [quick|notquick] [doit] [max_to_modify <Number>])|(ids <MessageIDEntity>)
        ((addlabel <LabelName>)|(removelabel <LabelName>))+
        [csv [todrive <ToDriveAttribute>*]]
gam <UserTypeEntity> spam messages|threads
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+
         [quick|notquick] [doit] [max_to_spam <Number>])|(ids <MessageIDEntity>)
        [csv [todrive <ToDriveAttribute>*]]
gam <UserTypeEntity> trash messages|threads
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+
         [quick|notquick] [doit] [max_to_trash <Number>])|(ids <MessageIDEntity>)
        [csv [todrive <ToDriveAttribute>*]]
gam <UserTypeEntity> untrash messages|threads
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+
         [quick|notquick] [doit] [max_to_untrash <Number>])|(ids <MessageIDEntity>)
        [csv [todrive <ToDriveAttribute>*]]

By default, the command results are displayed as indented keys and values. Use the csv option to display the command results in CSV form.

$ gam user user@domain.com delete messages ids 18e9fc6581b9acab,18e9fc58c5491f4c    
User: user@domain.com, Delete 2 Messages
  User: user@domain.com, Message: 18e9fc6581b9acab, Deleted (1/2)
  User: user@domain.com, Message: 18e9fc58c5491f4c, Deleted (2/2)
$ gam user user@domain.com delete messages ids 18e9fc6581b9acab,18e9fc58c5491f4c csv
User: user@domain.com, Delete 2 Messages
User,id,action,error
user@domain.com,18e9fc6581b9acab,Deleted,
user@domain.com,18e9fc58c5491f4c,Deleted,

Manage a specific set of messages

• ids <MessageIDEntity> - A list of message ids

Manage a selected set of messages

• ((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+ - Criteria to select messages
• max_to_xxx - Limit the number of messages that will be processed; use a value of 0 for no limit
• doit - No messages are processed unless you specify doit. By not specifying doit, you can preview the messages selected to verify that the results match your expectations.

When matchlabel <LabelName> is specified, the following characters are replaced with a - in the generated query.

 &()"|{}/

By default, Gam fetches all matching messages from Google and then processes only max_to_process of them. To speed up fetching, specify quick and only max_to_process of the matching messages will be fetched. You must still specify doit to perform the operation.

Delete messages by Message-Id

Sometimes multiple users in your domain receive an inappropriate message that you'd like to delete. From any user that received the message (or the one that sent it), you have to obtain the Message-Id. That looks like this:

Message-Id: <B1A91373-49E1-4235-8290-3E991E998A76@domain.com>

If you know Bob Smith sent the message or is someone you know received it and the subject is "New org chart next year", you can quickly find it like this:

gam user bob.smith@yourdomain.com print messages query "\"New org chart next year\"" headers subject,to,message-id

This will print a list of messages that match; by looking at the addressees, you can select which message ID(s) are relevant.

To delete the message for all users:

gam config auto_batch_min 1 all users delete message query "rfc822msgid:<B1A91373-49E1-4235-8290-3E991E998A76@domain.com>" doit

If your domain has many users, this process might still take a while. You can target a subset of users, for instance by Org unit or group. Refer to Collections of Users for all available options. For example, to target all users in the Org unit Sales:

gam config auto_batch_min 1 ou_and_children Sales delete message query "rfc822msgid:<B1A91373-49E1-4235-8290-3E991E998A76@domain.com>" doit

Or all users in the EastOffice group, including subgroups:

gam config auto_batch_min 1 groups_inde EastOffice delete message query "rfc822msgid:<B1A91373-49E1-4235-8290-3E991E998A76@domain.com>" doit

Display messages/threads

gam <UserTypeEntity> show messages|threads
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])*
         [quick|notquick] [max_to_show <Number>] [includespamtrash])|(ids <MessageIDEntity>)
        [labelmatchpattern <REMatchPattern>] [sendermatchpattern <REMatchPattern>]
        [countsonly|positivecountsonly] [useronly]
        [headers all|<SMTPHeaderList>] [dateheaderformat iso|rfc2822|<String>] [dateheaderconverttimezone [<Boolean>]]
        [showlabels] [delimiter <Character>] [showbody] [showhtml] [showdate] [showsize] [showsnippet]
        [maxmessagesperthread <Number>]
        [showattachments [attachmentnamepattern <REMatchPattern>>] [noshowtextplain]]
        [saveattachments [attachmentnamepattern <REMatchPattern>>]]
            [targetfolder <FilePath>] [overwrite [<Boolean>]]
gam <UserTypeEntity> print messages|threads [todrive <ToDriveAttribute>*]
        (((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])*
         [quick|notquick] [max_to_print <Number>] [includespamtrash])|(ids <MessageIDEntity>)
        [labelmatchpattern <REMatchPattern>] [sendermatchpattern <REMatchPattern>]
        [countsonly|positivecountsonly] [useronly]
        [headers all|<SMTPHeaderList>] [dateheaderformat iso|rfc2822|<String>] [dateheaderconverttimezone [<Boolean>]]
        [showlabels] [delimiter <Character>] [showbody] [showhtml] [showdate] [showsize] [showsnippet]
        [maxmessagesperthread <Number>]
        [showattachments [attachmentnamepattern <REMatchPattern>>]]
        [convertcrnl]

Display all messages

By default, Gam displays all messages.

• max_to_xxx - Limit the number of messages that will be displayed
• includespamtrash - Include messages in the Spam and Trash folders

By default, all messages in a thread are displayed with print|show threads. Use maxmessagesperthread <Number> to limit the number of messages displayed for a thread. For example, this can be used if you only want to see the first message of each thread.

gam user user@domain.com print|show threads maxmessagesperthread 1

Display a specific set of messages

• ids <MessageIDEntity> - A list of message ids

Display a selected set of messages

• ((query <QueryGmail> [querytime<String> <Date>]*) (matchlabel <LabelName>) [or|and])+ - Criteria to select messages
• max_to_xxx - Limit the number of messages that will be displayed
• includespamtrash - Include messages in the Spam and Trash folders
• labelmatchpattern <REMatchPattern> - Only display messages with some label that matches <REMatchPattern>
  • labelmatchpattern xyz - Label must start with xyz
  • labelmatchpattern .*xyz.* - Label must contain xyz
  • labelmatchpattern .*xyz - Label must end with xyz
  • labelmatchpattern ^xyz$ - Label must extctly match xyz
• sendermatchpattern <REMatchPattern> - Only display messages if the sender matches the <REMatchPattern>

When matchlabel <LabelName> is specified, the following characters are replaced with a - in the generated query.

 &()"|{}/

By default, Gam fetches only max_to_process matching messages from Google and then displays them. To see how many messages actually match, specify notquick and all matching messages will be fetched; only max_to_process of them will be displayed.

Difference between From and Sender headers

The From header specifies the author of the message, that is, the mailbox of the person or system responsible for the writing of the message. The Sender header specifies the mailbox of the agent responsible for the actual transmission of the message. For example, if a secretary were to send a message for another person, the mailbox of the secretary would appear in the Sender header and the mailbox of the actual author would appear in the From header.

The Gmail API supports querying the From header, but not the Sender header; thus, you must use sendermatchpattern <REMatchPattern> to query this header.

Choose information to display

By default, the fields User, threadId, id and these SMTP headers are displayed: Date, Subject, From, Reply-To, To, Delivered-To, Content-Type, Message-ID. Use these options to customize the display.

By default, the <SMTPDateHeader> values are displayed in RFC2822 format; the dateheaderformat iso|rfc2822|<String> option allows reformatting it:

• iso - Format is %Y-%m-%dT%H:%M:%S%:z
• rfc2822 - Format is %a, %d %b %Y %H:%M:%S %z
• <String> - Format according to: https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior If the Date header value can't be parsed as RFC2822, it is left unchanged.

The dateheaderconverttimezone [<Boolean>]> option converts <SMTPDateHeader> values to the gam.cfg timezone.

Display message content

• headers all - Display all SMTP headers
• headers <SMTPHeaderList> - Display only the SMTP headers listed
• showbody - Display the message body
• showhtml - When used in conjunction with showbody, display the message body if it is of type text/html
• showdate - Display the message internalDate
• showlabels - Display the message labels and count
  • useronly - Do not display system labels
  • delimiter <Character> - Separate the list of labels with <Character>; the default value is csv_output_field_delimiter from gam.cfg.
• showsize - Display the message size
• showsnippet - Display the message snippet

Display message counts

• countsonly - Display the count of the number of messages
• showsize - Display the cumulative message size

Display label counts

• showlabels - Display the message labels
• countsonly - Display all message label counts
• positivecountsonly - Display message label counts that are greater than 0
• showsize - Display the cumulative message size for each label
• useronly - Do not display system labels

Print only options

These options are valid with print.

• convertcrnl - In the message body, convert carriage returns to \r and newlines to \n; the default value is csv_output_convert_cr_nl from gam.cfg.

By default, message attachment information is not displayed.

• showattachments - Display attachment filename, MIME type and size
• attachmentnamepattern <REMatchPattern>> - Limit the attachments shown to those whose names match <REMatchPattern>

Show only options

These options are valid with show.

By default, message attachment information is not displayed.

• showattachments - Display message attachment content for MIME type text/plain, display filename, MIME type and size for other MIME types
  • noshowtextplain - Do not display message attachment content for MIME type text/plain, just display its filename, MIME type and size
• attachmentnamepattern <REMatchPattern>> - Limit the attachments shown to those whose names match <REMatchPattern>

Download attachments

These options are valid with show.

By default, message attachments are not downloaded.

• saveattachments - Download message attachments
• attachmentnamepattern <REMatchPattern>> - Limit the attachments downloaded to those whose names match <REMatchPattern>

By default, message attachments are downloaded to the directory specified in gam.cfg/drive_dir.

• targetfolder <FilePath> - Specify an alternate location for the downloaded attachments

The strings #email#, #user# and #username# will be replaced by the the user's full emailaddress or just the name portion in targetfolder <FilePath>.

By default, when downloading attachments, an existing local file will not be overwritten; a numeric prefix is added to the filename.

• overwrite - Overwite an existing file
• overwrite true - Overwite an existing file
• overwrite false - Do not overwite an existing file; add a numeric prefix and create a new file

Upload attachments

These options are valid with show.

By default, message attachments are not uploaded to Google Drive.

• uploadattachments - Upload message attachments
• attachmentnamepattern <REMatchPattern>> - Limit the attachments uploaded to those whose names match <REMatchPattern>

By default, message attachments are uploaded to the root of the user's My Drive.

• <DriveFileParentAttributeh> - Specify an alternate location for the uploaded attachments

Display messages sent by delegates for delegator

Display messages sent by a particular delegate for a delegator; the message is from the delegator but sent by the delegate.

$ gam user delegator show messages query "in:sent" sendermatchpattern delegate1@domain.com headers from,to,sender
Getting all Messages for delegator@domain.com
Got 24 Messages...
User: delegator@domain.com, Show maximum of 24 Messages of 24 Total Messages
  Message: 17a63d9f459cb9be (2/24)
    From: Test Simple <delegator@domain.com>
    To: ross.scroggs@gmail.com
    Sender: delegate1@domain.com

$ gam user delegator show messages query "in:sent" sendermatchpattern delegate2@domain.com headers from,to,sender
Getting all Messages for delegator@domain.com
Got 24 Messages...
User: delegator@domain.com, Show maximum of 24 Messages of 24 Total Messages
  Message: 17a63dc2cb14ed1e (1/24)
    From: Test Simple <delegator@domain.com>
    To: ross.scroggs@gmail.com
    Sender: delegate2@domain.com

$ gam user delegator show messages query "in:sent" sendermatchpattern "delegate.*@domain.com" headers from,to,sender
Getting all Messages for delegator@domain.com
Got 24 Messages...
User: delegator@domain.com, Show maximum of 24 Messages of 24 Total Messages
  Message: 17a63dc2cb14ed1e (1/24)
    From: Test Simple <delegator@domain.com>
    To: ross.scroggs@gmail.com
    Sender: delegate2@domain.com
  Message: 17a63d9f459cb9be (2/24)
    From: Test Simple <delegator@domain.com>
    To: ross.scroggs@gmail.com
    Sender: delegate1@domain.com

Display number of messages sent by delegates for a delegator; only delegates that sent messages will be displayed.

$ gam csv ./SentByDelegates.csv user delegator print messages query "in:sent" sendermatchpattern ".+" countsonly 
Getting all Messages for delegator@domain.com
Got 24 Messages...
$ more SentByDelegates.csv
User,Sender,messages
delegator@domain.com,delegate1@domain.com,1
delegator@domain.com,delegate2@domain.com,1