GSAK (Geocaching Swiss Army Knife)
Contents - Index

Pop3 (function)

Pop3(sAction,[sData] : string
Access Pop3 mail accounts. Pop3() is the successor to the now deprecated GetMail

The following "actions" are supported:

Connect - Connect/Login to the pop3 server. The return result is the number (as a string) of messages (depending on SetType) on the server

Delete - Delete the current message (via last "SetMsgNo" action) sData parameter is meaningless and can be omitted. This will physically remove the message from the pop3 server.

DisConnect - Disconnect from the Pop3 server and perform housekeeping clean up. sData parameter is meaningless and can be omitted. You should always use this action when finished with *all* pop3 actions.

GetBody - Get the Body of the current message (via last "SetMsgNo" action). sData is the number of lines to fetch. For speed optimization set this number to the lowest possible as required by the application. sData can be omitted, in which case the default used is 50.

GetBodyPlain - Behaves in the same way as GetBody, but will return the email body having the "text/plain" content type (if found/supported). This is usually just a stripped down version of the email body (removing HTML mark up etc) and should be better suited for visual and programmatic interrogation.

GetFrom - Get the "From" (sender) of the current message (via last "SetMsgNo" action). sData parameter is meaningless and can be omitted.

GetHeader - Get the full header for the current message (via last "SetMsgNo" action). sData parameter is meaningless and can be omitted.

GetSubject - Get the subject for the current message (via last "SetMsgNo" action). sData parameter is meaningless and can be omitted.

OnError - Same as "Error=" option for Sqlite(). If sData = "Halt" (Default) then any error will cause the macro to abort showing the corresponding error message. If sData = "Trap" then the macro will not abort, and any error causes the error message to be the result string of the pop3 function. All such strings will begin with "*Error*" (without the quotes). The macro author should then test the return string for such errors and react accordingly.
SaveAttachments - Save attachments for the current message (via last "SetMsgNo" action) . All attachments will be saved to the folder as specified in sData. The return value is the number of attachments saved (0 if there are no attachments). Resource wise, this is the most expensive action as the full email needs to be downloaded from the server.

SaveImages - Similar to "SaveAttachments" but will save any images to the folder specified by sData. These are typically image files (JPEGs,GIFs,PNG etc) that are included with HTML formatted messages with internal "CID" hyperlinks.

SetHost - Sets the pop3 host (sData). 

SetMsgNo - Set the message number (sData) for all other related actions (Delete, GetSubject, GetHeader, GetFrom, GetBody, SaveAttachments) to operate on

SetPass - Sets the password (sData) required to connect to the pop3 server

SetPort - Sets the pop3 port (sData). Default is 110, so only required if you want to connect to a pop3 server on a different port (Usually, 995 if connecting via SSL)

SetSsl - sData should be True or False. "True" forces a SSL connection on the current port (via SetPort). If a SSL connection can't be established then the function will end in error. "False" (default) establishes a non SSL connection on the current port (via SetPort).In reality, this action should never or rarely be needed. This is because the Pop3 function makes two exceptions behind the scenes. That is, when connecting on port 110 (the standard POP3 port) the pop3() function forces a non SSL connection regardless. When connecting on port 995 (the Standard SSL pop3 port) the pop3() function forces a SSL connection regardless. SSL protocols supported are: TLS 1.2,TLS 1.1,TLS 1.0,SSL 3.0
SetType - All = all messages on the server (read and unread) will be returned. Unread = Only unread messages will be returned. A message is considered as "read" when The GSAK pop3() function has accessed that message in any way (GetFrom, GetSubject, GetBody, GetBodyPlain, GetHeader, SaveAttachments, SaveImages).

SetUser - Sets the user name (sData) for the pop3 server.

SetUtf8 - sData should be "True" or "False", default is "False". GSAK does not support Unicode, but you may want the data to go into an application that does. When this value is set to "True" all return strings are UTF-8 encoded, preserving any Unicode characters.

For each of the following actions, you must have at least once used the SetMsgNo action in order to retrieve the required email data from the pop3 server:


The Following sample macro code will log into a pop3 server and show the subject of all emails for that account on the pop3 server:

$pop3 = Pop3("SetUser","")
$pop3 = Pop3("SetHost","")
$pop3 = Pop3("SetPass","*****")
$pop3 = Pop3("SetType","all")
ShowStatus msg=Connecting to Pop3 server
$pop3 = Pop3("connect")
$TotalMessages = val($pop3)
if $TotalMessages > 0
  $x = 0
    $x = $x + 1
    $Percent = int(($x/ $TotalMessages) * 100) 
    $pop3 = Pop3("SetMsgNo","$x")
    $Subject = Pop3("GetSubject")
    ShowStatus msg=$Subject Percent=$percent
  until $x = $TotalMessages
$Pop3 = Pop3("DisConnect")
Copyright 2004-2019 CWE Computer Services  
Privacy Policy Contact