g4gmail_listMessages

g4gmail_listMessages is used to list messages associated with a specific GMail Account. Any files associated with previously retrieved messages will be removed as well as the records in the associated files used for retrieving messages.

The process for retrieving messages is as follows:

• Retrieve list of messages matching the specifics of the query.

• Parse list and populate the G4GMMPF file with one record for each message.

• Read through the G4GMMPF file and for each record call the #g4gmail_getMessage() procedure which will populate the rest of the files (listed below). If get_parts is *YES then also retrieve any message parts (the parts will be embedded images, body text of the email, and any information regarding attachments).

• If get_attachments is *YES, then read through G4GMPPF (parts) file. Any record with an attachment ID that is not equal to blanks call the #g4gmail_getAttachment() procedure.

• If mark_as_read s *YES, read through the G4GMMPF file again and call the #g4gmail_markAsRead() procedure for each message ID.

The files listed in BOLD will actually be processed when #g4gmail_listMessages calls the #g4gmail_getMessage procedure internally.

• G4GMMPF - This is the GMail Message file. For each message retrieved there will be a record and the label it was retrieved from.

• G4GMHPF - This is the GMail Header file. For each message retrieved this file will contain the Google ID, Message ID, and a short snippet of the message

• G4GMHHPF - This is the GMail Header "Header" file. For each message retrieved this file will contain one entry for each header and the header value associated with the email. Headers are things like subject, to, from, etc.

• G4GMHLPF - This is the GMail Header "Label" file. For each message retrieved this will contain one or more values that represent the labels associated with that particular message. Labels are things like INBOX, SENT, TRASH or any customer labels you may have created. To get the description of each label you will need to use the G4GLSTML command to list the available labels and their descriptions.

• G4GMBPF - This is the GMail Message Body file. For each email that contains a "body" a record will be added here with a link to the stream file that the body is placed in. Normally a record will only be placed in this file when the email message is a plain text email with no attachments, images or other parts.

• G4GMPPF - This is the GMail Message "Part" file. When messages are retrieved each piece of it, including attachments and embedded images, etc, are known as "Parts". This file will contain one record for each part associated with each message retrieve. With most modern emails that are sent as text and html (multi-part) the actual content or message will be in one or more "parts".

Returns: Number of Messages, or -1 for error.

Optional Parameters:

• Error Message (output) - Error message

Settable Variables (use g4gmail_setValue):

• id (required) - Your Google ID

• label_id - The label ID to retrieve messages from. This is required only if you wish to move messages to another folder after they have been retrieved.

• include_spamtrash - Specify *YES or *NO in order to include (or not) messages marked as Spam or Trash in the results. The default is *NO.

• get_new_only - Specify *YES or *NO in order to retrieve only new messages, or all messages. The default is *YES.

• get_parts - Specify *YES or *NO in order to retrieve the message parts. This will be required to be *YES if you wish to retrieve attachments as well.

• get_attachments - Specify *YES or *NO to retrieve attachments associated with the messages retrieved.

• mark_as_read - Specify *YES or *NO to mark messages that are retrieved as read, or not.

• move_to_folder - If you wish to move the messages to another folder after they are retrieved, specify a folder ID to move them to. This is only valid if you have also specified a folder ID to retreive messages from.

• message_query - Specify a user defined query to use when retrieving messages. This is not checked for accuracy. You can find examples for this parameter at https://support.google.com/mail/answer/7190?hl=en.

• max_part_size - Specify the maximum part size (in bytes). Any email part larger than this value will not be downloaded. An entry will be logged in the G4GMPPF file with an error code of SIZE_LIMIT. The default is 16m. The size of the object reported by the API will be about 1.4 times larger than the actual size since the data is Base 64 encoded, so you may want to take that into account when specifying a size limit.

• ccsid - The CCSID to use. The default is 1208.

• debug - Specify *YES to turn on debug, or *NO to turn off debug. The default is *NO.

• debug_file - Specify the fully qualified file name for the main debug file. The default is /tmp/g4g_[id]_listMessagesDebug.txt.