Prev: Messaging

Module mail: E-Mail Messages

Compatibility of module mail Symbian 2nd Edition phones lack this module. Module not found

This module provides access to the e-mail accounts configured in the device. The main functions it offers are:

• Reading existing messages or message headers via mail.inbox and mail.get.
• Downloading body and attachments from the remote mailbox via mail.load.
• Synchronizing with the remote mailbox (i.e. downloading new messages) via mail.sync.
• Sending messages (with attachments) via mail.send.

Both POP3 and IMAP4 protocols are supported. The functions generally observe the account configuration (maximum number of messages, partial download, preferred internet access point, etc.).

e-mail messages are identified by numbers. These numbers are used to retrieve and load message contents, and to delete messages.

Before starting to work with a mailbox, it must be selected via mail.index. The subsequent calls to functions in this module will then operate on this mailbox.

• Example
• mail.boxes
• mail.conn
• mail.delete
• mail.from
• mail.get
• mail.inbox
• mail.index
• mail.load
• mail.open
• mail.send
• mail.set
• mail.sync

Example

The following example scans the first configured mailbox for all unread messages with subject "NEW IMAGES", stores all attached files in C:\data\images, and marks the message as read.

const PATH="c:\\data\\images\\" // a function to copy a stream into a file function copyfile(i, path)   o=io.create(path); buf=io.read(i, 256);   while buf#null do     io.write(o, buf); buf=io.read(i, 256)   end;   io.close(o) end // select the first mailbox mail.index(0); // synchronize it to get new messages mail.sync(); // scan for unread messages with proper subject for id in mail.inbox() do   m=mail.get(id);   if m["unread"] and m["subject"]="NEW IMAGES" then     // download the message body if required     if m["body"]=null then m=mail.load(id) end;     att=m["attached"];     if att#null then       for i=0 to len(att)-1 do         if isstr(att[i][0]) then // file?           copyfile(mail.open(id, i), .PATH+att[i][0])         end       end     end;     // mark the message as read     m["unread"]=false; mail.set(id, m)   end end; // stop synchronizing mail.conn(false)

mail.boxes

• function boxes() → Array
  Permissions: ReadApp

Returns the available mailboxes as an array. For each box, the following entries are provided:

Key	Meaning	Type
name	The mailbox name	String
type	The mailbox type (pop or imap)	String
server	The server host and port	String
user	The login user name	String

for box in mail.boxes() do   print box end → [private,pop,mail.private.ch:110,lknecht] [airbit,imap,mail.airbit.ch:143,Lucky Luke] [m-shell,imap,mail.airbit.ch:143,m Shell]

mail.conn

• function conn() → Boolean
• function conn(state) → Boolean
  Permissions: CostComm+ReadApp

Without arguments, returns the current connection state (true if a connection to the remote server mailbox exists, false otherwise).

With one argument, returns the current connection state, and sets the new connection state to state, i.e. connects if state=true and disconnects if state=false.

With IMAP4 mailboxes, connecting also starts mailbox synchronization, as with mail.sync.

Throws ErrNotReady if no mailbox has been selected.

// disconnect if a mailbox is selected if mail.index()>=0 then   mail.conn(false) end

mail.delete

• function delete(msgnum) → null
  Permissions: CostComm+WriteApp

Deletes the e-mail message with number msgnum from the inbox. msgnum must have been obtained via mail.inbox.

In general, the actual behaviour depends on the connection status:

• If there is a connection to the server, the message is deleted from the local inbox and the remote server.
• If there is no connection to the server, the message is marked as deleted in the local inbox.

The connection state can be changed with mail.conn.

Throws ErrNotFound if the message does not exist. Throws ErrNotReady if no mailbox has been selected.

// delete all e-mails marked with ``SPAM:'' for id in mail.inbox() do   m=mail.get(id);   if index(m["subject"], "SPAM:")=0 then     mail.delete(id)   end end

mail.from

• function from() → String
  Permissions: ReadApp

Returns the sender address of the current mailbox.

Throws ErrNotReady if no mailbox has been selected.

print mail.from() → info@m-shell.net

mail.get

• function get(msgnum) → Array
  Permissions: FreeComm+ReadApp

Gets the e-mail message with number msgnum from the inbox. The array returned has the following fields:

Key	Meaning	Type
from	The sender of the message	String
to	Recipients (only if message has been downloaded)	Array
cc	Carbon copy recipients (only if message has been downloaded)	Array
bcc	Blind carbon copy recipients (only if message has been downloaded)	Array
subject	Message subject	String
time	The time stamp of the message, as seconds since the start of year 0. See also module time.	Number
unread	true if the message is still unread, false if it has been seen.	Boolean
deleted	true if the message is marked as deleted, false if it is not marked.	Boolean
body	Message body text (only if message has been downloaded)	String
attached	Attachments (only if message has been downloaded and has attachments)	Array

Each entry in attached has two fields:

Index	Meaning	Type
0	File name (if attached file) or message number (if attached message)	String|Number
1	MIME type	String

Throws ErrNotFound if the message does not exist. Throws ErrNotReady if no mailbox has been selected.

// print sender and subject of all messages // in the inbox sent within the last 24 hours ago=time.get()-24*3600; for id in mail.inbox() do   m=mail.get(id);   if m["time"]>=ago then     print m["from"],m["subject"]   end end

See also: mail.load.

mail.inbox

• function inbox() → Array
  Permissions: FreeComm+ReadApp

Returns the numbers of all messages in the inbox of the currently selected mailbox.

Throws ErrNotReady if no mailbox has been selected.

print mail.inbox() → [1054329,1054328,1054327,1054326,1054325, 1054324,...<111>]

mail.index

• function index() → Number
• function index(boxIndex) → Number

Without arguments, returns the index of the currently selected mailbox in the array returned by mail.boxes. Returns -1 if no mailbox is selected.

With one argument, returns the index of the currently selected mailbox and selects the mailbox with index boxIndex. All subequent operations will occur on this mailbox.

Throws ExcIndexOutOfRange if the selected mailbox does not exist.

i=mail.index(); if i>=0 then   print mail.boxes()[i]["name"],"selected" else   print "No mailbox selected" end → m-shell selected

mail.load

• function load(msgnum, maxSize=0x7fffffff, timeout=-1) → Array|null
  Permissions: FreeComm+CostComm+ReadApp+WriteApp

Connects to the server if not already connected, then downloads the complete message with number msgnum, and returns it. Does not download the message if it is greater than maxSize bytes. If timeout>=0 and timeout milliseconds have passed without loading, null is returned.

The array returned has the same fields as if obtained via mail.get.

Throws ErrNotFound if the message does not exist. Throws ErrNotReady if no mailbox has been selected.

id=1054329 m=mail.get(id); // download if it is not complete yet if m["body"]=null then   m=mail.load(id) end print m["body"] → Hi mshell team I am a great fan of m-shell, but...

mail.open

• function open(msgnum, index) → Native Object
  Permissions: FreeComm+ReadApp

Opens the attachment with index index, and returns a stream object to read its data from. index is the index into msg.get(msgnum)["attached"].

Throws ErrNotFound if the message does not exist. Throws ErrNotReady if no mailbox has been selected. Throws ExcIndexOutOfRange if the attachment does not exist.

The returned stream can be accessed with most functions from module io:

• io.read, io.readln, and io.readm read data,
• io.size gets the total number of bytes,
• io.avail gets the number of bytes remaining,
• io.seek changes the read position,
• io.close closes the stream,
• io.ces gets and sets the character encoding scheme.

See the * () for an example using mail.open.

mail.send

• function send(recpts, subject, body, files=[], replyto=null) → null
  Permissions: CostComm+ReadApp

Sends an email message to the recipient(s) in recpts, with subject subject and body text body, attaching the files in files. If replyto#null, the Reply-To: field will be set accordingly.

The recipients in recpts can be specified in several ways:

• As a single e-mail address (String), which will become a To: address.
• As multiple e-mail addresses (Array), which will all become To: addresses.
• As an array with at least one of the following keys:
  

  Key	Meaning	Type
  to	To: address or addresses.	String|Array
  cc	Cc: address or addresses.	String|Array
  bcc	Bcc: address or addresses.	String|Array

Throws ErrNotReady if no mailbox has been selected.

// send a silly message to info@m-shell.net mail.send("info@m-shell.net", "I use m-shell",            "Hi!\n\nThis message was sent via " +           "the m mail module.") // send a foto "foto.jpg" to two friends, cc to yourself mail.send(["to":[friend1@gmail.com, friend2@gmail.com],            "cc":mail.from()],           "My latest pic",           "Hi friends!\n\nIsn't it great?",           ["foto.jpg"])

mail.set

• function set(msgnum, message) → null
  Permissions: WriteApp

Updates the e-mail message with number msgnum with the fields from message. Only the unread field can be modified, all other fields remain unchanged.

// mark all message in the inbox as unread for id in mail.inbox() do   mail.set(id, ["unread":true]) end

mail.sync

• function sync(all=false,timeout=-1) → Boolean|null
  Permissions: CostComm+WriteApp

Compatibility of function mail.sync With POP3 mailboxes, synchronization attempts when already connected to the remote server are silently ignored. Disconnect first with mail.conn(false). See also Forum Nokia, known issue KIS001156.

Connects to the remote e-mail server if not already connected, starts synchronizing the remote inbox with the local inbox in the device, and returns whether new messages were received since the start of the script or since the last call to mail.sync. If all=true, all message headers of a POP3 mailbox are downloaded, not only the new ones (for IMAP4 mailboxes, all is ignored). If timeout>=0 and timeout milliseconds have passed without connecting and downloading, null is returned.

The actual functions performed depend on the mailbox protocol (POP3 or IMAP4) and the configuration. Normal operations are:

• For POP3, downloads the message headers, and returns when the download is complete.
• For IMAP4, starts permanent synchronization with the remote server, then returns immediately. New messages will be downloaded when they arrive, the state of existing messages will be updated, and offline deleted messages may be removed from the server.

Use mail.conn to disconnect from the remote server.

Throws ErrNotReady if no mailbox has been selected.

// Wait for new messages, checking every minute // POP3 mailboxes require workaround for KIS001156 ispop=mail.boxes()[mail.index()]["type"]="pop"; while not mail.sync() do   if ispop then mail.conn(false) end; // disconnect   sleep(60000) end

---

Next: Module mms: Multimedia Messages

Navigation