Documentations

GMailer Object (libgmailer 0.7.0)

** bolded item: last updated in 0.7.0

Method Function

void setSessionMethod(GM_CONSTANT method) [0.6.4] To set the session handling method before connect. If you want PHP to handle it with cookie, set it to GM_USE_PHPSESSION|GM_USE_COOKIE; if you want PHP to handle it but without using cookie, set it to !GM_USE_COOKIE|GM_USE_PHPSESSION; if you do not want PHP to handle it, set it to GM_USE_COOKIE|!GM_USE_PHPSESSION. It will set to GM_USE_PHPSESSION|GM_USE_COOKIE by default.

void setLoginInfo(string name, string password, int GMT_timezone) To set the login information before connect.

void setProxy(string hostname, string username, string password) [0.6.4] To set the proxy information if necessary. If your proxy server does not require login, set "" to both username and password.

bool connect() To connect to GMail. It will use header() to set cookies at client-side browser. So you shouldn't output anything before calling this method, or use connectNoCookie() otherwise. It returns 1 if succeed, 0 otherwise.

bool connectNoCookie() To connect to GMail without storing any cookies at client-side browser. It returns 1 if succeed, 0 otherwise.

bool isConnected() To check if connected.

bool fetch(string query) To fetch the URL query result from GMail. It is intended to be used internally (private method). Use fetchBox() instead.

bool fetchBox(GM_CONSTANT type, string box, int position) [0.6.8] To fetch a result from GMail by given:
type: Gmailer constant, e.g. GM_LABEL.
box: name of "box" (e.g. Inbox, your_label, "all"/"freq" of contacts)
position: cursor for paged result.

bool fetchContact() use fetchBox() indeed after 0.6.8.

GMailSnapshot getSnapshot(GM_CONSTANT type) To get a "snapshot", an object (see GMailSnapshot below) for you to access query result at ease.

bool getAttachment(string attachment_id, string message_id, string filename, bool zipped) [0.7.0] To download an attachment of a message. If zipped is true, download ALL attachements of message_id in a zip file.

array getAttachmentsOf(array GMailSnapshot->conv, string path_to_store_files) To download ALL files attached to a conversation. The full path of downloaded files will be returned (as array).

bool send(string to, string subject, string body, string cc, string bcc, string message_replying, string thread_replying, array attachments, bool draft_saving, string draft_id) [0.6.8] To send gmail or save drafts. to, cc and bcc are comma-separated addresses. attachments is an array of names of files to be attached.

bool performAction(GM_CONSTANT action_type, array message_id, string label) To perform action on message. message_id can be a string if only one message to be acted.

void disconnect() To disconnect from gmail. Any cookies set at client-side browser by libgmailer will be removed.

string dump(string query) To dump ALL it gets from URL query string, including headers.

array getStandardBox() To get an array of names of the "standard box" (Inbox, Starred, etc.)

bool invite(string email) [0.7.0] Send invite to email. Note: it will still return true if you have no invite to send. It returns false only when GMailer encounter errors.

Constant Description

GM_STANDARD All about "Standard Box" (Inbox, Sent, All, Starred, Spam, Trash).

GM_LABEL All about labels.

GM_CONVERSATION All about conversation.

GM_QUERY All about search query.

GM_CONTACT All about contact list.

GM_ACT_APPLYLABEL / GM_ACT_REMOVELABEL Apply/remove label from message.

GM_ACT_STAR / GM_ACT_UNSTAR Star/unstar a message.

GM_ACT_SPAM / GM_ACT_UNSPAM Mark/unmark message as spam.

GM_ACT_READ / GM_ACT_UNREAD Mark message as read/unread.

GM_ACT_ARCHIVE / GM_ACT_INBOX Move message away from/to Inbox.

GM_ACT_TRASH / GM_ACT_UNTRASH Move message to/away from Trash.

GM_ACT_DELFOREVER Delete message forever.

GM_ACT_UNDRAFT [0.6.8] Discard a draft.

GM_ACT_TRASHMSG [0.7.0] Trash an individual message (not entire conversation).

GM_ACT_DELSPAM [0.7.0] Delete (forever) a spam. Yes! Everybody hate spam.

GM_ACT_DELTRASHED [0.7.0] Delete (forever) a conversation in Trash.

GM_USE_PHPSESSION [0.6.4] Use PHP Session to handle gmail-lite session.

GM_USE_COOKIE [0.6.4] Use cookie to handle gmail-lite session.

Some example:

A typical code sequence for fetching gmails is:

   require("libgmailer.php");
   
   $gm = new GMailer();
   $gm->setLoginInfo($name, $pwd, $tz);  // only required for connecting the first time, 
                                         // e.g. in your login page
                                         // in other pages you can simply connect()
   if ($gm->connect()) {
      $gm->fetchBox(GM_LABEL, "my_label", 0);  // name of constants can be found in libgmailer.php
      $snapshot = $gm->getSnapshot(GM_LABEL);
      if ($snapshot) {
         echo "Total # of conversations of my_label = " . $snapshot->box_total;
         /** etc etc **/
      }
      // $gm->disconnect() only when you really want to logout
   }

Sending new gmails with libgmailer is also simple:

   require("libgmailer.php");
   
   $gm = new GMailer();
   if ($gm->connect()) {
      $to = "who@what.com, my_friend@his_company.com, god@heaven.org";
      $cc = "foo@bar.com";
      $subj = "Hello There!";
      $message = "Hi...\n\nBlah blah blah~...";
      $attachments = array("./my_pic.jpg", "./my_cv.txt");   
      $gm->send($to, $subj, $message, $cc, 0, 0, 0, $attachments, false, 0);
   }

Playing around with contact list...

   require("libgmailer.php");   
   $gm = new GMailer();
   if ($gm->connect()) {
      $gm->fetchBox(GM_CONTACT, "freq", 0);
      $snapshot = $gm->getSnapshot(GM_CONTACT);
      echo "Your frequently used addresses:";
      foreach ($snapshot->contacts as $item) {
         echo "Name: " . $item["name"] . " Email: " . $item["email"];
      }
   }

More details soon...

GMailSnapshot Object (libgmailer 0.6.4 - 0.7.0)

GMailSnapshot can only be created by calling GMailer->getSnapshot(type). You have to specify the type of snapshot you would like to get when calling. A typical code sequence of getting a snapshot is:

   /** assume connected already **/
   switch ($what_you_want) {
      case 1:
         $gmailer->fetchBox(GM_STANDARD, "inbox", 0);
         $snapshot = $gmailer->getSnapshot(GM_STANDARD);
         break;
      case 2:
         $gmailer->fetchBox(GM_LABEL, "my_label", 0);
         $snapshot = $gmailer->getSnapshot(GM_LABEL);
         break;
      case 3:
         $gmailer->fetchBox(GM_QUERY, $my_query_string, 0);
         $snapshot = $gmailer->getSnapshot(GM_QUERY);
         break;
      case 4:
         $gmailer->fetchBox(GM_CONVERSATION, $conversation_id, 0);
         $snapshot = $gmailer->getSnapshot(GM_CONVERSATION);
         break;
      case 5:
         $gmailer->fetchBox(GM_CONTACT, "all", 0);
         $snapshot = $gmailer->getSnapshot(GM_CONTACT);
         break;
      default:
         die();
   }

Once you obtained a snapshot, you can play around with its properties:

Properties available to snapshot type: all except GM_CONTACT

Property Description

gmail_ver Version of GMail javascript core program

quota_mb Mailbox quota in MB

quota_per Mailbox quota in percentage

std_box_new Number-indexed Array. Number of unread mails in each standard boxes. You may call GMailer::getStandardBox() to get an array of names of standard boxes.

have_invit Number of invites you have. 0 = no invitation, etc.

label_list Number-indexed Array. An array of label names.

label_new Number-indexed Array. Number of unread mails in each labels. (An 1-to-1 mapping of label_list.)

Properties available to snapshot type: GM_STANDARD, GM_LABEL, GM_QUERY

Property Description

box_name Name of the standard box/label or query string currently viewing.

box_total Total number of conversations in current mailbox.

box_pos Current starting position (for paged results).

box Number-indexed Array. An array of conversations in current mailbox. Each conversation is an text-indexed array of following:

Index Description

id Conversation ID

is_read 0 = read; 1 = not read yet.

is_starred 0 = not starred; 1 = starred.

date Arrival date/time of the most recent message.

sender Senders of message in this conversation.

flag Flag.

subj Subject of this conversation.

snippet "Snippet", or preview of this conversation.

labels Number-indexed Array. Name of labels that this conversation is bearing.

attachment Number-indexed Array. Name of all attaching files of this conversation.

msgid Message ID of the most recently received message of this conversation.

Example (to get the subject of 6-th conversation of current viewing box): $snapshot->box[5]["subj"]

Properties available to snapshot type: GM_CONVERSATION

Property Description

conv_title Subject (title) of this conversation.

conv_total Total number of messages in this conversation.

conv_id Conversation ID.

conv_labels Number-indexed Array. Name of labels that this conversation is bearing.

conv_starred [0.6.4] Is the conversation starred? This is true if any of the messages of a conversation is starred.

conv Number-indexed Array. An array of messages of current conversation. Each message is an text-indexed array of following:

Index Description

index Index.

id Message ID.

is_draft Is draft or not.

draft_parent Replying message ID of this draft.

sender Name of sender of this message.

sender_email Email address of the sender.

recv Name of recevier of this message.

recv_email Email address of the receiver.

reply_email Replying address of this message.

cc_email CC address of this message (draft).

bcc_email BCC address of this message (draft).

dt_easy Arrival date/time of this message in "easy" format, e.g. 9 Aug (2 days ago).

dt Arrival date/time of this message in "long" format, e.g. Mon, 9 Aug 2004 19:34:03 +0800.

subj Subject of this message.

is_starred [0.6.4] Is the message starred?

snippet "Snippet", or preview of this message.

body Message body.

attachment Number-indexed Array. An array of attachment-information, which is an text-indexed array of the following:

Index Description

id Attachment ID.

filename Filename of this attching file.

type File type (e.g. JPG, GIF, PDF) of this attaching file.

size Size in bytes of this file.

Example: $snapshot->conv[3]["attachment"][1]["size"] (size of the 2nd attaching file of the 4th messages of current conversation)

Properties available to snapshot type: GM_CONTACT

Property Description

contacts Number-indexed Array. Array of entries (see below) of your address book.

Index Description

name Name (nickname).

email Email address.

notes Notes.

Method	Function
`void setSessionMethod(GM_CONSTANT method)` [0.6.4]	To set the session handling method before connect. If you want PHP to handle it with cookie, set it to `GM_USE_PHPSESSION\|GM_USE_COOKIE`; if you want PHP to handle it but without using cookie, set it to `!GM_USE_COOKIE\|GM_USE_PHPSESSION`; if you do not want PHP to handle it, set it to `GM_USE_COOKIE\|!GM_USE_PHPSESSION`. It will set to `GM_USE_PHPSESSION\|GM_USE_COOKIE` by default.
`void setLoginInfo(string name, string password, int GMT_timezone)`	To set the login information before connect.
`void setProxy(string hostname, string username, string password)` [0.6.4]	To set the proxy information if necessary. If your proxy server does not require login, set "" to both username and password.
`bool connect()`	To connect to GMail. It will use `header()` to set cookies at client-side browser. So you shouldn't output anything before calling this method, or use `connectNoCookie()` otherwise. It returns 1 if succeed, 0 otherwise.
`bool connectNoCookie()`	To connect to GMail without storing any cookies at client-side browser. It returns 1 if succeed, 0 otherwise.
`bool isConnected()`	To check if connected.
`bool fetch(string query)`	To fetch the URL query result from GMail. It is intended to be used internally (private method). Use `fetchBox()` instead.
`bool fetchBox(GM_CONSTANT type, string box, int position)` [0.6.8]	To fetch a result from GMail by given: `type`: Gmailer constant, e.g. `GM_LABEL`. `box`: name of "box" (e.g. Inbox, your_label, "all"/"freq" of contacts) `position`: cursor for paged result.
`bool fetchContact()`	use `fetchBox()` indeed after 0.6.8.
`GMailSnapshot getSnapshot(GM_CONSTANT type)`	To get a "snapshot", an object (see GMailSnapshot below) for you to access query result at ease.
`bool getAttachment(string attachment_id, string message_id, string filename, bool zipped)` [0.7.0]	To download an attachment of a message. If `zipped` is true, download ALL attachements of `message_id` in a zip file.
`array getAttachmentsOf(array GMailSnapshot->conv, string path_to_store_files)`	To download ALL files attached to a conversation. The full path of downloaded files will be returned (as array).
`bool send(string to, string subject, string body, string cc, string bcc, string message_replying, string thread_replying, array attachments, bool draft_saving, string draft_id)` [0.6.8]	To send gmail or save drafts. `to`, `cc` and `bcc` are comma-separated addresses. `attachments` is an array of names of files to be attached.
`bool performAction(GM_CONSTANT action_type, array message_id, string label)`	To perform action on message. `message_id` can be a string if only one message to be acted.
`void disconnect()`	To disconnect from gmail. Any cookies set at client-side browser by libgmailer will be removed.
`string dump(string query)`	To dump ALL it gets from URL query string, including headers.
`array getStandardBox()`	To get an array of names of the "standard box" (Inbox, Starred, etc.)
`bool invite(string email)` [0.7.0]	Send invite to `email`. Note: it will still return `true` if you have no invite to send. It returns `false` only when GMailer encounter errors.
Constant	Description
`GM_STANDARD`	All about "Standard Box" (Inbox, Sent, All, Starred, Spam, Trash).
`GM_LABEL`	All about labels.
`GM_CONVERSATION`	All about conversation.
`GM_QUERY`	All about search query.
`GM_CONTACT`	All about contact list.
`GM_ACT_APPLYLABEL` / `GM_ACT_REMOVELABEL`	Apply/remove label from message.
`GM_ACT_STAR` / `GM_ACT_UNSTAR`	Star/unstar a message.
`GM_ACT_SPAM` / `GM_ACT_UNSPAM`	Mark/unmark message as spam.
`GM_ACT_READ` / `GM_ACT_UNREAD`	Mark message as read/unread.
`GM_ACT_ARCHIVE` / `GM_ACT_INBOX`	Move message away from/to Inbox.
`GM_ACT_TRASH` / `GM_ACT_UNTRASH`	Move message to/away from Trash.
`GM_ACT_DELFOREVER`	Delete message forever.
`GM_ACT_UNDRAFT` [0.6.8]	Discard a draft.
`GM_ACT_TRASHMSG` [0.7.0]	Trash an individual message (not entire conversation).
`GM_ACT_DELSPAM` [0.7.0]	Delete (forever) a spam. Yes! Everybody hate spam.
`GM_ACT_DELTRASHED` [0.7.0]	Delete (forever) a conversation in Trash.
`GM_USE_PHPSESSION` [0.6.4]	Use PHP Session to handle gmail-lite session.
`GM_USE_COOKIE` [0.6.4]	Use cookie to handle gmail-lite session.