phpDocumentor GMailer
[ class tree: GMailer ] [ index: GMailer ] [ all elements ]

Class: GMailer

Source Location: /libgmailer.php

Class GMailer

Class Overview

Class GMailer is the main class/library for interacting with Gmail (Google's free webmail service) with ease.

Acknowledgement
It is not completely built from scratch. It is based on: "Gmail RSS feed in PHP" by thimal, "Gmail as an online backup system" by Ilia Alshanetsky, and "Gmail Agent API" by Johnvey Hwang and Eric Larson.

Special thanks to Eric Larson and all other users, testers, and forum posters for their bug reports, comments and advices.

Located in /libgmailer.php [line 156]



		
				Author(s):
		
		
		
Information Tags:
Version:  0.8.0-rc
Link:  Sourceforge project page
Link:  Project homepage

Properties

Methods

[ Top ]
Property Summary
bool   $created  
mixed[]   $return_status   Status of GMailer

[ Top ]
Method Summary
GMailer   GMailer()   Constructor of GMailer
bool   addSenderToContact()   Add message's senders to contact list.
bool   connect()   Connect to GMail with default session management settings.
bool   connectNoCookie()   Connect to Gmail without setting any session/cookie
bool   deleteContact()   Delete contacts.
bool   deleteFilter()   Delete a filter.
void   disconnect()   Disconnect from Gmail.
string   dump()   Dump everything to output.
bool   editContact()   Create/edit contact.
bool   editFilter()   Create/edit a filter.
bool   editLabel()   Create, edit or remove label.
bool   fetch()   Fetch contents by URL query.
bool   fetchBox()   Fetch contents from Gmail by type.
bool   getAttachment()   Save attachment with attachment ID $attid and message ID $msgid to file with name $filename.
string[]   getAttachmentsOf()   Save all attaching files of conversations to a path.
bool   getCookieFromBrowser()   Get cookies from browser.
bool   getSessionFromBrowser()   Recover session information.
GMailSnapshot   getSnapshot()   Get GMailSnapshot by type.
string[]   getStandardBox()   Get names of standard boxes.
bool   invite()   Send Gmail invite to $email
bool   isConnected()   See if it is connected to GMail.
string   lastActionStatus()   Last action's action, status, message, and other info
bool   performAction()   Perform action on messages.
bool   removeCookieFromBrowser()   Remove all related cookies stored in browser.
bool   removeSessionFromBrowser()   Remove all session information related to Gmailer.
bool   saveCookieToBrowser()   Save (send) cookies to browser.
bool   saveSessionToBrowser()   Save session data.
bool   send()   Send Gmail. Or save a draft email.
bool   setGeneralSetting()   Set general settings of Gmail account.
void   setLoginInfo()   Set Gmail's login information.
void   setProxy()   Setting proxy server.
void   setSessionMethod()   Setting session management method.
bool   starMessageQuick()   Star/unstar a message quickly.

[ Top ]
Properties
bool   $created [line 187]
API Tags:
Access:  public


[ Top ]
mixed[]   $return_status = array() [line 199]

Status of GMailer

If something is wrong, check this class property to see what is going wrong.

API Tags:
Access:  public

Information Tags:
Since:  8 July 2005
Author:  Neerav

[ Top ]
Methods
Constructor GMailer  [line 248]

  GMailer GMailer( )

Constructor of GMailer

During the creation of GMailer object, it will perform several tests to see if the cURL extension is available or not. However, note that the constructor will NOT return false or null even if these tests are failed. You will have to check the class property GMailer::$created to see if the object "created" is really, uh, created (i.e. working), and property GMailer::$return_status or method GMailer::lastActionStatus() to see what was going wrong.

Example:

  1. <?php
  2. $gmailer = new GMailer();
  3. if (!$gmailer->created) {
  4. echo "Error message: ".$gmailer->lastActionStatus("message");
  5. } else {
  6. // Do something with $gmailer
  7. }
  8. ?>

A typical usage og GMailer object would be like this:

  1. <?php
  2. require_once("libgmailer.php");
  3.  
  4. $gmailer = new GMailer();
  5. if ($gmailer->created) {
  6. $gmailer->setLoginInfo($gmail_acc, $gmail_pwd, $my_timezone);
  7. $gmailer->setProxy("proxy.company.com");
  8. if ($gmailer->connect()) {
  9. // GMailer connected to Gmail successfully.
  10. // Do something with it.
  11. } else {
  12. die("Fail to connect because: ".$gmailer->lastActionStatus());
  13. }
  14. } else {
  15. die("Failed to create GMailer because: ".$gmailer->lastActionStatus());
  16. }
  17. ?>


API Tags:
See:  GMailer::$created, GMailer::$return_status, GMailer::lastActionStatus()


[ Top ]
addSenderToContact  [line 1848]

  bool addSenderToContact( string $message_id  )

Add message's senders to contact list.

Parameters:
string   $message_id:  Message ID

Information Tags:
Since:  14 Aug 2005
Author:  Neerav

[ Top ]
connect  [line 559]

  bool connect( )

Connect to GMail with default session management settings.


API Tags:
Return:  Connect to Gmail successfully or not


[ Top ]
connectNoCookie  [line 425]

  bool connectNoCookie( )

Connect to Gmail without setting any session/cookie


API Tags:
Return:  Connect to Gmail successfully or not


[ Top ]
deleteContact  [line 1990]

  bool deleteContact( string[] $id  )

Delete contacts.

Parameters:
string[]   $id:  Contact ID to be deleted

API Tags:
Return:  Success or not.

Information Tags:
Since:  15 Jun 2005
Author:  Neerav

[ Top ]
deleteFilter  [line 2320]

  bool deleteFilter( string $id  )

Delete a filter.

Parameters:
string   $id:  Filter ID to be deleted

API Tags:
Return:  Success or not.

Information Tags:
Since:  25 Jun 2005
Author:  Neerav

[ Top ]
disconnect  [line 1325]

  void disconnect( )

Disconnect from Gmail.



[ Top ]
dump  [line 849]

  string dump( string $query  )

Dump everything to output.

This is a "low-level" method. Use the method GMailer::fetchBox() to fetch standard contents from Gmail.

Parameters:
string   $query:  URL query string.

API Tags:
Return:  Everything received from Gmail.


[ Top ]
editContact  [line 1715]

  bool editContact( string $contact_id, string $name, string $email, string $notes, [mixed[][] $details = array()]  )

Create/edit contact.

Examples:

  1. <?php
  2. // Add a new one
  3. $gmailer->editContact(-1,
  4. "John",
  5. "john@company.com",
  6. "Supervisor of project X",
  7. "");
  8.  
  9. // Add a new one with lots of details
  10. $gmailer->editContact(-1, "Mike", "mike@company.com",
  11. "Mike the driver",
  12. array(array("phone" => "123-45678",
  13. "mobile" => "987-65432",
  14. "fax" => "111-11111",
  15. "pager" => "222-22222",
  16. "im" => "34343434",
  17. "company" => "22th Century Fox",
  18. "position" => "CEO",
  19. "other" => "Great football player!",
  20. "address" => "1 Fox Rd",
  21. "detail_name" => "Mike G. Stone"));
  22.  
  23. // Modified an existing one
  24. $gmailer->editContact($contact_id,
  25. "Old Name",
  26. "new_mail@company.com",
  27. "Old notes");
  28. ?>

Note: You must supply the old name even if you are not going to modify it, or it will be changed to empty!

Parameters:
string   $contact_id:  Contact ID for editing an existing one, or -1 for creating a new one
string   $name:  Name
string   $email:  Email address
string   $notes:  Notes
mixed[][]   $details:  Detailed information

API Tags:
Return:  Success or not.

Information Tags:
Since:  15 Jun 2005
Author:  Neerav

[ Top ]
editFilter  [line 2197]

  bool editFilter( integer $filter_id, string $from, string $to, string $subject, string $has, string $hasnot, bool $hasAttach, bool $archive, bool $star, bool $label, string $label_name, bool $forward, string $forwardto, bool $trash  )

Create/edit a filter.

Parameters:
integer   $filter_id:  Filter ID to be edited, or "0" for creating a new one
string   $from: 
string   $to: 
string   $subject: 
string   $has: 
string   $hasnot: 
bool   $hasAttach: 
bool   $archive: 
bool   $star: 
bool   $label: 
string   $label_name: 
bool   $forward: 
string   $forwardto: 
bool   $trash: 

API Tags:
Return:  Success or not.

Information Tags:
Since:  25 Jun 2005
Author:  Neerav

[ Top ]
editLabel  [line 2082]

  bool editLabel( string $label, string $action, string $renamelabel  )

Create, edit or remove label.

Parameters:
string   $label: 
string   $action:  Either "create", "delete" or "rename"
string   $renamelabel:  New name if renaming label

API Tags:
Return:  Success or not.

Information Tags:
Since:  7 Jun 2005
Author:  Neerav

[ Top ]
fetch  [line 642]

  bool fetch( string $query  )

Fetch contents by URL query.

This is a "low-level" method. Please use GMailer::fetchBox() for fetching standard contents.

Parameters:
string   $query:  URL query string

API Tags:
Return:  Success or not


[ Top ]
fetchBox  [line 714]

  bool fetchBox( constant $type, mixed $box, int $parameter  )

Fetch contents from Gmail by type.

Content can be one of the following categories:

  1. GM_STANDARD: For standard mail-boxes like Inbox, Sent Mail, All, etc. In such case, $box should be the name of the mail-box: "inbox", "all", "sent", "draft", "spam", or "trash". $paramter would be used for paged results.
  2. GM_LABEL: For user-defined label. In such case, $box should be the name of the label.
  3. GM_CONVERSATION: For conversation. In such case, $box should be the conversation ID.
  4. GM_QUERY: For search query. In such case, $box should be the query string.
  5. GM_PREFERENCE: For Gmail preference. In such case, $box = "".
  6. GM_CONTACT: For contact list. In such case, $box can be either "all", "search" or "detail". When $box = "detail", $parameter is the Contact ID. When $box = "search", $parameter is the search query string.

Parameters:
constant   $type:  Content category
mixed   $box:  Content type
int   $parameter:  Extra parameter. See above.

API Tags:
Return:  Success or not
See:  GM_STANDARD, GM_LABEL, GM_CONVERSATION, GM_QUERY, GM_PREFERENCE, GM_CONTACT


[ Top ]
getAttachment  [line 805]

  bool getAttachment( string $attid, string $msgid, string $filename, [bool $zipped = false]  )

Save attachment with attachment ID $attid and message ID $msgid to file with name $filename.

Parameters:
string   $attid:  Attachment ID.
string   $msgid:  Message ID.
string   $filename:  File name.
bool   $zipped:  Save all attachment of message ID $msgid into a zip file.

API Tags:
Return:  Success or not.


[ Top ]
getAttachmentsOf  [line 771]

  string[] getAttachmentsOf( string[] $convs, string $path  )

Save all attaching files of conversations to a path.

Random number will be appended to the new filename if the file already exists.

Parameters:
string[]   $convs:  Conversations.
string   $path:  Local path.

API Tags:
Return:  Name of the files saved. False if failed.


[ Top ]
getCookieFromBrowser  [line 1186]

  bool getCookieFromBrowser( )

Get cookies from browser.


API Tags:
Return:  Success or not.


[ Top ]
getSessionFromBrowser  [line 1156]

  bool getSessionFromBrowser( )

Recover session information.


API Tags:
Return:  Success or not.


[ Top ]
getSnapshot  [line 1378]

  GMailSnapshot getSnapshot( constant $type  )

Get GMailSnapshot by type.

Examples:

  1. <?php
  2. // For "Inbox"
  3. $gmailer->fetchBox(GM_STANDARD, "inbox", 0);
  4. $snapshot = $gmailer->getSnapshot(GM_STANDARD);
  5.  
  6. // For conversation
  7. $gmailer->fetchBox(GM_CONVERSATION, $thread_id, 0);
  8. $snapshot = $gmailer->getSnapshot(GM_CONVERSATION);
  9. ?>

Parameters:
constant   $type: 

API Tags:
See:  GM_STANDARD, GM_LABEL, GM_CONVERSATION, GM_QUERY, GM_PREFERENCE, GM_CONTACT
See:  GMailSnapshot


[ Top ]
getStandardBox  [line 1471]

  string[] getStandardBox( )

Get names of standard boxes.


API Tags:
Deprecated:  
Static:  


[ Top ]
invite  [line 1402]

  bool invite( string $email  )

Send Gmail invite to $email

Parameters:
string   $email: 

API Tags:
Return:  Success or not. Note that it will still be true even if $email is an illegal address.


[ Top ]
isConnected  [line 589]

  bool isConnected( )

See if it is connected to GMail.



[ Top ]
lastActionStatus  [line 599]

  string lastActionStatus( [string $request = "message"]  )

Last action's action, status, message, and other info

Parameters:
string   $request:  What information you would like to request. Default is "message".


[ Top ]
performAction  [line 1041]

  bool performAction( constant $act, string[] $id, [string $para = ""]  )

Perform action on messages.

Examples:

  1. <?php
  2. // Apply label to $message_id
  3. $gmailer->performAction(GM_ACT_APPLYLABEL, $message_id, "my_label");
  4.  
  5. // Star $message_id
  6. $gmailer->performAction(GM_ACT_STAR, $message_id);
  7.  
  8. // more examples...
  9. ?>

Parameters:
constant   $act:  Action to be performed.
string[]   $id:  Message ID.
string   $para:  Action's parameter:
  1. GM_ACT_APPLYLABEL, GM_ACT_REMOVELABEL: Name of the label.

API Tags:
Return:  Success or not. If returned false, please check GMailer::$return_status or GMailer::lastActionStatus() for error message.


[ Top ]
removeCookieFromBrowser  [line 1295]

  bool removeCookieFromBrowser( )

Remove all related cookies stored in browser.



[ Top ]
removeSessionFromBrowser  [line 1264]

  bool removeSessionFromBrowser( )

Remove all session information related to Gmailer.


API Tags:
Return:  Success or not.


[ Top ]
saveCookieToBrowser  [line 1240]

  bool saveCookieToBrowser( )

Save (send) cookies to browser.


API Tags:
Return:  Success or not.


[ Top ]
saveSessionToBrowser  [line 1220]

  bool saveSessionToBrowser( )

Save session data.


API Tags:
Return:  Success or not.


[ Top ]
send  [line 915]

  bool send( string $to, string $subj, string $body, [string $cc = ""], [string $bcc = ""], [string $mid = ""], [string $tid = ""], [string[] $files = 0], [bool $draft = false], [string $orig_df = ""], [bool $is_html = 0], [string $from = ""]  )

Send Gmail. Or save a draft email.

Examples:

  1. <?php
  2. // Simplest usage: send a new mail to one person:
  3. $gmailer->send("who@what.com", "Hello World", "Cool!\r\nFirst mail!");
  4.  
  5. // More than one recipients. And with CC:
  6. $gmailer->send("who@what.com, boss@company.com",
  7. "Hello World",
  8. "This is second mail.",
  9. "carbon-copy@company.com");
  10.  
  11. // With file attachment
  12. $gmailer->send("who@what.com",
  13. "Your file",
  14. "Here you are!",
  15. "", "", "", "",
  16. array("path/to/file.zip", "path/to/another/file.tar.gz"));
  17.  
  18. // more examples...
  19. ?>

Parameters:
string   $to:  Recipient's address. Separated by comma for multiple recipients.
string   $subj:  Subject line of email.
string   $body:  Message body of email.
string   $cc:  Address for carbon-copy (CC). Separated by comma for multiple recipients. $cc = "" for none.
string   $bcc:  Address for blind-carbon-copy (BCC). Separated by comma for multiple recipients. $bcc = "" for none.
string   $mid:  Message ID of the replying email. $mid = "" if this is a newly composed email.
string   $tid:  Conversation (thread) ID of the replying email. $tid = "" if this is a newly composed email.
string[]   $files:  File names of files to be attached.
bool   $draft:  Indicate this email is saved as draft, or not.
string   $orig_df:  If this email is saved as a modified draft, then set $orig_df as the draft ID of the original draft.
bool   $is_html:  HTML-formatted mail, or not.
string   $from:  Send mail as this email address (personality). $from = "" to use your Gmail address (NOT the default one in your settings). Note: you will NOT send your mail successfully if you do not register this address in your Gmail settings panel.

API Tags:
Return:  Success or not. If returned false, please check GMailer::$return_status or GMailer::lastActionStatus() for error message.

Information Tags:
Since:  9 September 2005

[ Top ]
setGeneralSetting  [line 2408]

  bool setGeneralSetting( bool $use_outgoing_name, string $outgoing_name, bool $use_reply_email, string $reply_to, string $language, int $page_length, bool $shortcut, bool $indicator, bool $snippet, bool $custom_signature, string $signature, string $forward_to, string $forward_action, int $pop_setting, int $pop_action, [bool $expand_label_box = 1], [bool $expand_invite_box = 1]  )

Set general settings of Gmail account.

Parameters:
bool   $use_outgoing_name:  Use outgoing name (instead of the default)?
string   $outgoing_name:  Outgoing name
bool   $use_reply_email:  Use replying email address (instead of the default)?
string   $reply_to:  Replying email address
string   $language:  Language
int   $page_length:  Page length. Must be either 25, 50 or 100
bool   $shortcut:  Enable keyboard shortcut?
bool   $indicator:  Enable personal level indicator?
bool   $snippet:  Enable snippet?
bool   $custom_signature:  Enable custom signature?
string   $signature:  Custom signature
string   $forward_to:  Address to auto-forward to. $forward_to = "" to disable auto-forward
string   $forward_action:  Action on Gmail's copy of auto-forwarded emails. $forward_action = "" to keep them, "archive" to archive them, or "trash" to trash them
int   $pop_setting:  POP settings. $pop_setting = 0 to disable POP access, 1 to remain unchanged, 2 to enable POP for new mails, or 3 to enable POP for all mails
int   $pop_action:  Action on Gmail's copy of POP-accessed emails. $pop_action = 0 to keep them, 1 to archive them, or 2 to trash them
bool   $expand_label_box:  Expand label box?
bool   $expand_invite_box:  Expand invite box?

API Tags:
Return:  Success or not.

Information Tags:
Since:  29 Jun 2005
Author:  Neerav

[ Top ]
setLoginInfo  [line 312]

  void setLoginInfo( string $my_login, string $my_pwd, float $my_tz  )

Set Gmail's login information.

Parameters:
string   $my_login:  Gmail's login name (without @gmail.com)
string   $my_pwd:  Password
float   $my_tz:  Timezone with respect to GMT, but in decimal. For example, -2.5 for -02:30GMT


[ Top ]
setProxy  [line 345]

  void setProxy( string $host, string $username, string $pwd  )

Setting proxy server.

Example:

  1. <?php
  2. // proxy server requiring login
  3. $gmailer->setProxy("proxy.company.com", "my_name", "my_pwd");
  4.  
  5. // proxy server without login
  6. $gmailer->setProxy("proxy2.company.com", "", "");
  7. ?>

Parameters:
string   $host:  Proxy server's hostname
string   $username:  User name if login is required
string   $pwd:  Password if required


[ Top ]
setSessionMethod  [line 379]

  void setSessionMethod( int $method  )

Setting session management method.

You have to select a session management method so that GMailer would "remember" your identity. Method has to be one of the following values:

  1. GM_USE_COOKIE | !GM_USE_PHPSESSION (if your server does not have PHP Session installed)
  2. !GM_USE_COOKIE | GM_USE_PHPSESSION (if your server have PHP Session installed, and don't want to set browser's cookie)
  3. GM_USE_COOKIE | GM_USE_PHPSESSION (if your server have PHP Session installed, and would like to use cookie to store session)

Parameters:
int   $method: 


[ Top ]
starMessageQuick  [line 1918]

  bool starMessageQuick( string $message_id, string $action  )

Star/unstar a message quickly.

Parameters:
string   $message_id: 
string   $action:  Either "star" or "unstar".

API Tags:
Return:  Success or not.

Information Tags:
Author:  Neerav

[ Top ]

Documentation generated on Sat, 10 Sep 2005 06:06:41 +0800 by phpDocumentor 1.3.0RC3