diff --git a/lua_examples/email/read_email_imap.lua b/lua_examples/email/read_email_imap.lua index bbd22b6b..02289aec 100644 --- a/lua_examples/email/read_email_imap.lua +++ b/lua_examples/email/read_email_imap.lua @@ -1,71 +1,119 @@ --- -- @author Miguel (AllAboutEE.com) --- @description Reads email via IMAP +-- @description This example will read the first email in your inbox using IMAP and +-- display it through serial. The email server must provided unecrypted access. The code +-- was tested with an AOL and Time Waraner cable email ccounts (GMail and other services who do +-- not support no SSL access will not work). --- this could be your email (and it is in most cases even in you have a "username") require("imap") -local IMAP_USERNAME = "myemail@domain.com" -local IMAP_PASSWORD = "myemailpassword" +local IMAP_USERNAME = "email@domain.com" +local IMAP_PASSWORD = "password" -local IMAP_SERVER = "imap.domain.com" +-- find out your unencrypted imap server and port +-- from your email provided i.e. google "[my email service] imap settings" for example +local IMAP_SERVER = "imap.service.com" local IMAP_PORT = "143" -local IMAP_TAG = "t1" + +local IMAP_TAG = "t1" -- You do not need to change this +local IMAP_DEBUG = false -- change to true if you would like to see the entire conversation between + -- the ESP8266 and IMAP server local SSID = "ssid" -local SSID_PASSWORD = "ssidpassword" +local SSID_PASSWORD = "password" -local count = 0 +local count = 0 -- we will send several IMAP commands/requests, this variable helps keep track of which one to send +-- configure the ESP8266 as a station wifi.setmode(wifi.STATION) wifi.sta.config(SSID,SSID_PASSWORD) wifi.sta.autoconnect(1) +-- create an unencrypted connection local imap_socket = net.createConnection(net.TCP,0) +--- +-- @name setup +-- @description A call back function used to begin reading email +-- upon sucessfull connection to the IMAP server function setup(sck) + -- Set the email user name and password, IMAP tag, and if debugging output is needed imap.config(IMAP_USERNAME, IMAP_PASSWORD, IMAP_TAG, - sck) + IMAP_DEBUG) - imap.login(imap_socket) + imap.login(sck) end -imap_socket:on("connection",setup) -imap_socket:connect(IMAP_PORT,IMAP_SERVER) +imap_socket:on("connection",setup) -- call setup() upon connection +imap_socket:connect(IMAP_PORT,IMAP_SERVER) -- connect to the IMAP server +local subject = "" +local from = "" +local message = "" + +--- +-- @name do_next +-- @description A call back function for a timer alarm used to check if the previous +-- IMAP command reply has been processed. If the IMAP reply has been processed +-- this function will call the next IMAP command function necessary to read the email function do_next() - if(imap.receive_complete() == true) then - print("receive complete") + -- Check if the IMAP reply was processed + if(imap.response_processed() == true) then + + -- The IMAP reply was processed if (count == 0) then - print("Examine:\r\n") + -- After logging in we need to select the email folder from which we wish to read + -- in this case the INBOX folder imap.examine(imap_socket,"INBOX") count = count + 1 elseif (count == 1) then - imap.fetch_header(imap_socket,1,"SUBJECT") + -- After examining/selecting the INBOX folder we can begin to retrieve emails. + imap.fetch_header(imap_socket,imap.get_most_recent_num(),"SUBJECT") -- Retrieve the SUBJECT of the first/newest email count = count + 1 elseif (count == 2) then - imap.fetch_header(imap_socket,1,"FROM") + subject = imap.get_header() -- store the SUBJECT response in subject + imap.fetch_header(imap_socket,imap.get_most_recent_num(),"FROM") -- Retrieve the FROM of the first/newest email count = count + 1 elseif (count == 3) then - imap.fetch_body_plain_text(imap_socket,1) + from = imap.get_header() -- store the FROM response in from + imap.fetch_body_plain_text(imap_socket,imap.get_most_recent_num()) -- Retrieve the BODY of the first/newest email count = count + 1 elseif (count == 4) then - imap.logout(imap_socket) + body = imap.get_body() -- store the BODY response in body + imap.logout(imap_socket) -- Logout of the email account count = count + 1 else - print("The body is: ".. imap.get_body()) - tmr.stop(0) - imap_socket:close() - collectgarbage() + -- display the email contents + + -- create patterns to strip away IMAP protocl text from actual message + pattern1 = "(\*.+\}\r\n)" -- to remove "* n command (BODY[n] {n}" + pattern2 = "(\r\n.+)" -- to remove ") t1 OK command completed" + + from = string.gsub(from,pattern1,"") + from = string.gsub(from,pattern2,"") + print(from) + + subject = string.gsub(subject,pattern1,"") + subject = string.gsub(subject,pattern2,"") + print(subject) + + body = string.gsub(body,pattern1,"") + body = string.gsub(body,pattern2,"") + print("Message: " .. body) + + tmr.stop(0) -- Stop the timer alarm + imap_socket:close() -- close the IMAP socket + collectgarbage() -- clean up end end end +-- A timer alarm is sued to check if an IMAP reply has been processed tmr.alarm(0,1000,1, do_next) diff --git a/lua_modules/email/imap.lua b/lua_modules/email/imap.lua index 589481e4..4b2031ab 100644 --- a/lua_modules/email/imap.lua +++ b/lua_modules/email/imap.lua @@ -1,3 +1,19 @@ +--- +-- IMPORTANT: run node.compile("imap.lua") after uploading this script +-- to create a compiled module. Then run file.remove("imap.lua") +-- @name imap +-- @description An IMAP 4rev1 module that can be used to read email. +-- Tested on NodeMCU 0.9.5 build 20150213. +-- @date March 12, 2015 +-- @author Miguel +-- GitHub: https://github.com/AllAboutEE +-- YouTube: https://www.youtube.com/user/AllAboutEE +-- Website: http://AllAboutEE.com +-- +-- Visit the following URLs to learn more about IMAP: +-- "How to test an IMAP server by using telnet" http://www.anta.net/misc/telnet-troubleshooting/imap.shtml +-- "RFC 2060 - Internet Message Access Protocol - Version 4rev1" http://www.faqs.org/rfcs/rfc2060.html +------------------------------------------------------------------------------------------------------------- local moduleName = ... local M = {} _G[moduleName] = M @@ -9,71 +25,180 @@ local SERVER = "" local PORT = "" local TAG = "" -local body = "" +local DEBUG = false + +local body = "" -- used to store an email's body / main text +local header = "" -- used to store an email's last requested header field e.g. SUBJECT, FROM, DATA etc. +local most_recent_num = 1 -- used to store the latest/newest email number/id -local receive_complete = false +local response_processed = false -- used to know if the last IMAP response has been processed -function M.receive_complete() - return receive_complete +--- +-- @name response_processed +-- @returns The response process status of the last IMAP command sent +function M.response_processed() + return response_processed end - +--- +-- @name display +-- @description A generic IMAP response processing function. +-- Can disply the IMAP response if DEBUG is set to true. +-- Sets the reponse processed variable to true when the string "complete" +-- is found in the IMAP reply/response local function display(socket, response) - print(response) - if(string.match(response,'complete') ~= nil) then - receive_complete = true + + -- If debuggins is enabled print the IMAP response + if(DEBUG) then + print(response) end + + -- Some IMAP responses are long enough that they will cause the display + -- function to be called several times. One thing is certain, IMAP will replay with + -- " OK complete" when it's done sending data back. + if(string.match(response,'complete') ~= nil) then + response_processed = true + end + end -function M.config(username,password,tag,sk) +--- +-- @name config +-- @description Initiates the IMAP settings +function M.config(username,password,tag,debug) USERNAME = username PASSWORD = password TAG = tag + DEBUG = debug end +--- +-- @name login +-- @descrpiton Logs into a new email session function M.login(socket) - receive_complete = false + response_processed = false -- we are sending a new command + -- which means that the response for it has not been processed socket:send(TAG .. " LOGIN " .. USERNAME .. " " .. PASSWORD .. "\r\n") socket:on("receive",display) end +--- +-- @name get_most_recent_num +-- @returns The most recent email number. Should only be called after examine() +function M.get_most_recent_num() + return most_recent_num +end + +--- +-- @name set_most_recent_num +-- @description Gets the most recent email number from the EXAMINE command. +-- i.e. if EXAMINE returns "* 4 EXISTS" this means that there are 4 emails, +-- so the latest/newest will be identified by the number 4 +local function set_most_recent_num(socket,response) + + if(DEBUG) then + print(response) + end + + local _, _, num = string.find(response,"([0-9]+) EXISTS(\.)") -- the _ and _ keep the index of the string found + -- but we don't care about that. + + if(num~=nil) then + most_recent_num = num + end + + if(string.match(response,'complete') ~= nil) then + response_processed = true + end +end + +--- +-- @name examine +-- @description IMAP examines the given mailbox/folder. Sends the IMAP EXAMINE command function M.examine(socket,mailbox) - receive_complete = false + response_processed = false socket:send(TAG .. " EXAMINE " .. mailbox .. "\r\n") - socket:on("receive",display) + socket:on("receive",set_most_recent_num) end +--- +-- @name get_header +-- @returns The last fetched header field +function M.get_header() + return header +end + +--- +-- @name set_header +-- @description Records the IMAP header field response in a variable +-- so that it may be read later +local function set_header(socket,response) + if(DEBUG) then + print(response) + end + + header = header .. response + if(string.match(response,'complete') ~= nil) then + response_processed = true + end +end + +--- +-- @name fetch_header +-- @description Fetches an emails header field e.g. SUBJECT, FROM, DATE +-- @param socket The IMAP socket to use +-- @param msg_number The email number to read e.g. 1 will read fetch the latest/newest email +-- @param field A header field such as SUBJECT, FROM, or DATE function M.fetch_header(socket,msg_number,field) - - receive_complete = false + header = "" -- we are getting a new header so clear this variable + response_processed = false socket:send(TAG .. " FETCH " .. msg_number .. " BODY[HEADER.FIELDS (" .. field .. ")]\r\n") - socket:on("receive",display) + socket:on("receive",set_header) end + +--- +-- @name get_body +-- @return The last email read's body function M.get_body() return body end - +--- +-- @name set_body +-- @description Records the IMAP body response in a variable +-- so that it may be read later local function set_body(socket,response) - print(response) + + if(DEBUG) then + print(response) + end + body = body .. response if(string.match(response,'complete') ~= nil) then - receive_complete = true + response_processed = true end end +--- +-- @name fetch_body_plain_text +-- @description Sends the IMAP command to fetch a plain text version of the email's body +-- @param socket The IMAP socket to use +-- @param msg_number The email number to obtain e.g. 1 will obtain the latest email function M.fetch_body_plain_text(socket,msg_number) -receive_complete = false - body = "" + response_processed = false + body = "" -- clear the body variable since we'll be fetching a new email socket:send(TAG .. " FETCH " .. msg_number .. " BODY[1]\r\n") socket:on("receive",set_body) end +--- +-- @name logout +-- @description Sends the IMAP command to logout of the email session function M.logout(socket) - receive_complete = false + response_processed = false socket:send(TAG .. " LOGOUT\r\n") socket:on("receive",display) end