imap

Top  Previous  Next

IMAP is an extension by Promixis to the socket namespace. This class is fairly low level an understanding of the IMAP protocol will certainly help using this class.

 

Some resources on IMAP can be found here:

 

http://tools.ietf.org/html/rfc3501

http://www.skytale.net/blog/archives/23-Manual-IMAP.html

http://www.imapwiki.org/ClientImplementation

http://networking.ringofsaturn.com/Protocols/imap.php

Methods

 

Return

Signature

Description

IMAP object

new ( server, port, sslProtocol, timeout )

constructor

result, err

connect()

connect to server

result, err

login( username, password )

login to the server

result, err

logout()

logout from the server

result, boxes

getMailBoxes()

Gets a list of mailboxes

result, imapResult

examine( mailBox )

Runs an EXAMINE command on the mailbox

result, imapResult

select( mailBox )

Selects the mailbox as current, required for functions below

result, messageIds

unseen()

Gets a list of ids for messages that have not yet been read.

result, message

fetchMessage( messageId, peek )

Gets the message.

result, err

addFlags( messageId, flags )

Adds flags to the message flag list

result, err

removeFlags( messageId, flags )

Removes flags from the message flag list

result, imapResult

query( query )

Advanced function to run your own IMAP queries.

new

Creates the new object

imap = socket.imap.new( server, port, sslProtocol, timeout )

 

Name

Type

Description

imap

IMAP Object

The IMAP object

server

string

server name

port

number

port number to connect to

sslProtocol

string

ssl to use or empty ( sslv3, tlsv1 or sslv23 )

timeout

number

timeout to use for all operations

connect

Connects the object to the server. Returns true on success.

result, err = imap:connect()

Name

Type

Description

result

boolean

True on success, nil on error

err

string

Reason for error

login

logs into the server

result, err = imap:login( username, password )

Name

Type

Description

result

boolean

True on success, nil on error

err

string

Reason for error

username

string

username for login

password

string

password for login

logout

logs out from the server

result, err = imap:logout( )

Name

Type

Description

result

boolean

True on success, nil on error

err

string

Reason for error

getMailBoxes

gets a list of available mailboxes

result, mailboxes = imap:getMailBoxes( )

Name

Type

Description

result

boolean

True on success, nil on error

mailboxes

string or table of mailbox details ( mailbox.flags, mailbox.path, mailbox.name )

Reason for error or mailbox details

examine

Performs the IMAP EXAMINE command on the mailbox.

result, msg = imap:examine( mailbox )

Name

Type

Description

result

boolean

True on success, nil on error

msg

string or table of IMAP results see

http://tools.ietf.org/html/rfc3501#section-6.3.2

Reason for error or details

select

Sets the mailbox as the currently selected box. This is necessary before you can do unseen fetchMessage, addFlags or removeFlags

result, msg = imap:select( mailbox )

Name

Type

Description

result

boolean

True on success, nil on error

msg

string or table of IMAP results see

http://tools.ietf.org/html/rfc3501#section-6.3.1

Reason for error or details

unseen

gets a list of messages that have not yet been marked unseen ( aka UNREAD )

result, msg = imap:unseen( )

Name

Type

Description

result

boolean

True on success, nil on error

msg

string or table or message ids

Reason for error or list of message ids that can be passed to fetchMessage

fetchMessage

Fetches a message from the server

result, message = imap:fetchMessage( messageId, peek )

Name

Type

Description

result

boolean

True on success, nil on error

message

string

reason for error or message header + body

messageId

number

id of message obtained from unseen

peek

boolean

if set to true the message will not be marked as \Seen upon fetch

addFlags, removeFlags

Adjusts the flags on a message.

result, err = imap:addFlags( messageId, flags )

Name

Type

Description

result

boolean

True on success, nil on error

err

string

reason for error

messageId

number

id of message obtained from unseen

flags

string

Message flags to add or remove see http://tools.ietf.org/html/rfc3501#section-2.3.2

 

Running custom requests

To run custom requests study the imap.lua file and the use the imap:request(requestString) function to perform any operation you like.

 

Example

The following example show how you can get the oldest unseen message from the gmail IMAP server. Depending on the content of the message you could trigger events. This would allow you to make Girder do certain actions from email.

 

imap = require('socket.imap')

= imap.new( "imap.gmail.com", 993, "tlsv1", 1000)

 

if not i:connect() then

 print("Failed to connected")

 return

end

 

if not i:login("youremail@gmail.com", "yourpassword") then

 print("Login failed.")

 return

end

 

-- Select your desired mailbox

if not i:select("Inbox") then

 print("Could not select mailbox")

 return

end

 

-- get a list of unseen messages

local status, unseenMessageList = i:unseen()

if not status then

 print("Could not get list of unseen messages")

 return

end

 

if #unseenMessageList == 0 then

 print("No unseen messages")

 return

end

 

-- get the first unseen message marking it as seen.

local status, message = i:fetchMessage( unseenMessageList[ 1 ], false )

if not status then

 print("Could not get message")

 return

end

 

 

print( message )

 

i:deinit()

= nil