Sometimes the developers want to leave a copy of email on the POP3/IMAP4/Exchange server for backup, so they don't delete the email after the email was received. The common issue is how to detect if the email has been retrieved by the application already, otherwise, all the emails on the server will be retrieved again and again. In this case, we should use the Unique Identifier (UIDL) to avoid to receive the same email more than once.
Using Unique Identifier (UIDL)
The mail server assigns an unique identifier for every email in the same account. You can get the UIDL for every email by MailInfo.UIDL property. To avoid to receive the same email twice, the best way is storing the UIDL of email retrieved to a text file or database. Next time before you retrieve the email, compare your local uidl list with remote uidl. If this uidl exists in your local uidl list, then you don't receive it, otherwise you should receive it.
Difference with UIDL in POP3/IMAP4/Exchange Web Service/WebDAV
UIDL is always unique in IMAP4 and it is always increasing integer. UIDL in POP3 can be any valid asc-ii characters, and the UIDL may be reused by POP3 server if the email with the UIDL has been deleted from the server, so we suggest that you should remove the uidl from your local uidl list if the uidl is no longer existed on the POP3 server. UIDL is also unique in Exchange Web Service/WebDAV, but the UIDL is string but not integer. Every email has a unique identifier (UIDL) on IMAP4 server. It is a 32bit integer and it is always unique in your email account life time. So we can use the integer as file name to identify if the email has been downloaded. There is a little bit different in POP3 server. The UIDL is only unique in the email life time. That means if the email was deleted from the server, other email can use the old unique identifier. Another problem is: UIDL in POP3 server can be any number or characters, so we cannot use UIDL as the file name, because UIDL may contain invalid characters for file name. For Exchange Web Service/WebDAV, although the UIDL is always unique in your email account, but UIDL may also contain invalid characters for file name.
Total Solution
UIDLManager provides an easy way to maintain UIDL between your server and your local client. How does it work? It stores UIDL collection to a local disk file and you can use this object to add, remove and search UIDL with this local file.
UIDL File Format
With UIDLManager, you can use any file name as the UIDL local file, but we suggest that you use different UIDL file for different email account. In the UIDL file, each line presents a UIDL information.
"mailserver#user#protocol","UIDL","Local File Name","Download Date Time","Flags"
"mailserver#user#protocol","UIDL1","Local File Name1","Download Date Time","Flags"
You can use UIDLManager to record the UIDL of the email that you have downloaded; you can also associate the local file name and flags to UIDLItem object. Then you can use UIDLManager to detect if the email has been downloaded, when it has been downloaded. If it has been downloaded, what local file it has saved to.
Example
[[Visual Basic 6.0, VBScript, Visual C++, Delphi] The following example demonstrates how To retrieve email with EAGetMail POP3 & IMAP Component, but it doesn't demonstrates the events and mail parsing usage. To get the full samples of EAGetMail, please refer to Samples section.
[Visual Basic 6.0]
Const MailServerPop3 = 0
Const MailServerImap4 = 1
Const MailServerEWS = 2
Const MailServerDAV = 3
Const MailServerMsGraph = 4
Public Sub ReceiveMail( _
ByVal sServer As String, _
ByVal sUserName As String, _
ByVal sPassword As String, _
ByVal bSSLConnection As Boolean, _
ByVal bLeaveCopy)
Dim currentPath As String
Dim localInbox As String
Dim isUidlLoaded As Boolean
isUidlLoaded = False
' Create a folder named "inbox" under current directory
' to save the email retrieved.
currentPath = App.Path
localInbox = currentPath & "\inbox"
Dim oTools As New EAGetMailObjLib.Tools
oTools.CreateFolder localInbox
Dim oServer As New EAGetMailObjLib.MailServer
oServer.Server = sServer
oServer.User = sUserName
oServer.Password = sPassword
oServer.Protocol = MailServerPop3
oServer.SSLConnection = bSSLConnection
If oServer.SSLConnection Then
oServer.Port = 995
Else
oServer.Port = 110
End If
On Error GoTo ErrorHandle:
' uidl is the identifier of every email on POP3/IMAP4 server, to avoid retrieve
' the same email from server more than once, we record the email uidl retrieved every time
' if you delete the email from server every time and not to leave a copy of email on
' the server, then please remove all the function about uidl.
' If you want to re-download all emails, please delete uidl.txt from local inbox.
' uidl is the identifier of every email on POP3/IMAP4 server, to avoid retrieve
' the same email from server more than once, we record the email uidl retrieved every time
' if you delete the email from server every time and not to leave a copy of email on
' the server, then please remove all the function about uidl.
' If you want to re-download all emails, please delete uidl.txt from local inbox.
Dim oUIDLManager As New EAGetMailObjLib.UIDLManager
oUIDLManager.Load localInbox & "\uidl.txt"
isUidlLoaded = True
Dim oClient As New EAGetMailObjLib.MailClient
oClient.LicenseCode = "TryIt"
oClient.Connect oServer
MsgBox "Connected"
Dim mailInfos As EAGetMailObjLib.MailInfoCollection
Set mailInfos = oClient.GetMailInfoList()
MsgBox mailInfos.Count & " emails"
' Remove the local uidl that is not existed on the server,
oUIDLManager.SyncUIDLEX oServer, mailInfos
' Update result back to uidl file
oUIDLManager.Update
Dim i As Long
For i = 0 To mailInfos.Count - 1
Dim oInfo As EAGetMailObjLib.MailInfo
Set oInfo = mailInfos.Item(i)
MsgBox "Index: " & i + 1 & "; Size: " & oInfo.Size & _
"; UIDL: " & oInfo.UIDL
Dim oUIDLItem As UIDLItem
Set oUIDLItem = oUIDLManager.FindUIDL(oServer, oInfo.UIDL)
' If this email has not been retrieved before, then get it
If oUIDLItem Is Nothing Then
Dim fileName As String
fileName = oTools.GenFileName(i + 1) & ".eml"
Dim fullFileName As String
fullFileName = localInbox & "\" & fileName
Dim oMail As EAGetMailObjLib.Mail
Set oMail = oClient.GetMail(oInfo)
oMail.SaveAs fullFileName, True
If bLeaveCopy Then
' Add the email uidl to uidl file to avoid we retrieve it next time.
oUIDLManager.AddUIDL oServer, oInfo.UIDL, fileName
Else
oClient.Delete oInfo
' Remove UIDL from local uidl file.
oUIDLManager.RemoveUIDL oServer, oInfo.UIDL
End If
End If
Next
' Quit
oClient.Quit
' Update the uidl list to a text file and then we can load it next time.
oUIDLManager.Update
Exit Sub
ErrorHandle:
MsgBox Err.Description
If isUidlLoaded Then
' Update the uidl list to a text file and then we can load it next time.
oUIDLManager.Update
End If
End Sub
[VBScript]
Const MailServerPop3 = 0
Const MailServerImap4 = 1
Const MailServerEWS = 2
Const MailServerDAV = 3
Const MailServerMsGraph = 4
Public Sub ReceiveMail( _
ByVal sServer , _
ByVal sUserName, _
ByVal sPassword, _
ByVal bSSLConnection, _
ByVal bLeaveCopy)
Dim localInbox
Dim isUidlLoaded
isUidlLoaded = False
' Create a folder named "inbox"
' to save the email retrieved.
localInbox = "d:\inbox"
Dim oTools
Set oTools = CreateObject("EAGetMailObj.Tools")
oTools.CreateFolder localInbox
Dim oServer
Set oServer = CreateObject("EAGetMailObj.MailServer")
oServer.Server = sServer
oServer.User = sUserName
oServer.Password = sPassword
oServer.Protocol = MailServerPop3
oServer.SSLConnection = bSSLConnection
If oServer.SSLConnection Then
oServer.Port = 995
Else
oServer.Port = 110
End If
' uidl is the identifier of every email on POP3/IMAP4 server, to avoid retrieve
' the same email from server more than once, we record the email uidl retrieved every time
' if you delete the email from server every time and not to leave a copy of email on
' the server, then please remove all the function about uidl.
' If you want to re-download all emails, please delete uidl.txt from local inbox.
' uidl is the identifier of every email on POP3/IMAP4 server, to avoid retrieve
' the same email from server more than once, we record the email uidl retrieved every time
' if you delete the email from server every time and not to leave a copy of email on
' the server, then please remove all the function about uidl.
' If you want to re-download all emails, please delete uidl.txt from local inbox.
Dim oUIDLManager
Set oUIDLManager = CreateObject("EAGetMailObj.UIDLManager")
oUIDLManager.Load localInbox & "\uidl.txt"
isUidlLoaded = True
Dim oClient
Set oClient = CreateObject("EAGetMailObj.MailClient")
oClient.LicenseCode = "TryIt"
oClient.Connect oServer
WScript.Echo "Connected"
Dim mailInfos
Set mailInfos = oClient.GetMailInfoList()
WScript.Echo mailInfos.Count & " emails"
' Remove the local uidl that is not existed on the server,
oUIDLManager.SyncUIDLEX oServer, mailInfos
' Update result back to uidl file
oUIDLManager.Update
Dim i
For i = 0 To mailInfos.Count - 1
Dim oInfo
Set oInfo = mailInfos.Item(i)
WScript.Echo "Index: " & i + 1 & "; Size: " & oInfo.Size & _
"; UIDL: " & oInfo.UIDL
Dim oUIDLItem
Set oUIDLItem = oUIDLManager.FindUIDL(oServer, oInfo.UIDL)
' If this email has not been retrieved before, then get it
If oUIDLItem Is Nothing Then
Dim fileName
fileName = oTools.GenFileName(i + 1) & ".eml"
Dim fullFileName
fullFileName = localInbox & "\" & fileName
Dim oMail
Set oMail = oClient.GetMail(oInfo)
oMail.SaveAs fullFileName, True
If bLeaveCopy Then
' Add the email uidl to uidl file to avoid we retrieve it next time.
oUIDLManager.AddUIDL oServer, oInfo.UIDL, fileName
Else
oClient.Delete oInfo
' Remove UIDL from local uidl file.
oUIDLManager.RemoveUIDL oServer, oInfo.UIDL
End If
End If
Next
' Quit
oClient.Quit
' Update the uidl list to a text file and then we can load it next time.
oUIDLManager.Update
End Sub
[Visual C++]
#include "stdafx.h"
#include <windows.h>
#include "eagetmailobj.tlh"
using namespace EAGetMailObjLib;
DWORD _getCurrentPath(LPTSTR lpPath, DWORD nSize)
{
DWORD dwSize = ::GetModuleFileName(NULL, lpPath, nSize);
if (dwSize == 0 || dwSize == nSize)
{
return 0;
}
// Change file name to current full path
LPCTSTR psz = _tcsrchr(lpPath, _T('\\'));
if (psz != NULL)
{
lpPath[psz - lpPath] = _T('\0');
return _tcslen(lpPath);
}
return 0;
}
int _tmain(int argc, _TCHAR* argv[])
{
const int MailServerPop3 = 0;
const int MailServerImap4 = 1;
const int MailServerEWS = 2;
const int MailServerDAV = 3;
const int MailServerMsGraph = 4;
// Initialize COM environment
::CoInitialize(NULL);
/// Create a folder named "inbox" under current exe file directory
// to save the emails retrieved.
TCHAR szPath[MAX_PATH + 1];
_getCurrentPath(szPath, MAX_PATH);
TCHAR szMailBox[MAX_PATH + 1];
wsprintf(szMailBox, _T("%s\\inbox"), szPath);
// Create a folder to store emails
::CreateDirectory(szMailBox, NULL);
IUIDLManagerPtr uidlManager;
bool isUidlLoaded = false;
// leave a copy of message on server
bool leaveCopy = true;
try
{
IMailServerPtr oServer = NULL;
oServer.CreateInstance(__uuidof(EAGetMailObjLib::MailServer));
oServer->Server = _T("pop3.emailarchitect.net");
oServer->User = _T("test@emailarchitect.net");
oServer->Password = _T("testpassword");
oServer->Protocol = MailServerPop3;
// Enable SSL/TLS connection, most modern email servers require SSL/TLS by default
oServer->SSLConnection = VARIANT_TRUE;
oServer->Port = 995;
// If your POP3 doesn't deploy SSL connection
// Please use
// oServer->SSLConnection = VARIANT_FALSE;
// oServer->Port = 110;
IMailClientPtr oClient = NULL;
oClient.CreateInstance(__uuidof(EAGetMailObjLib::MailClient));
oClient->LicenseCode = _T("TryIt");
// uidl is the identifier of every email on POP3/IMAP4 server, to avoid retrieve
// the same email from server more than once, we record the email uidl retrieved every time
// if you delete the email from server every time and not to leave a copy of email on
// the server, then please remove all the function about uidl.
TCHAR szUidlFile[MAX_PATH + 1];
wsprintf(szUidlFile, _T("%s\\uidl.txt"), szMailBox);
uidlManager.CreateInstance(__uuidof(EAGetMailObjLib::UIDLManager));
uidlManager->Load(szUidlFile);
isUidlLoaded = true;
oClient->Connect(oServer);
_tprintf(_T("Connected\r\n"));
IMailInfoCollectionPtr infos = oClient->GetMailInfoList();
_tprintf(_T("Total %d emails\r\n"), infos->Count);
// Remove the local uidl that is not existed on the server,
uidlManager->SyncUIDLEX(oServer, infos);
uidlManager->Update();
for (long i = 0; i < infos->Count; i++)
{
IMailInfoPtr pInfo = infos->GetItem(i);
IUIDLItemPtr uidl = uidlManager->FindUIDL(oServer, pInfo->UIDL);
if (uidl != nullptr)
{
// This email has been downloaded before
continue;
}
// Generate an unique file named based on current date time
// If you don't like it, you can use your method to generate file name
TCHAR szFile[MAX_PATH + 1];
SYSTEMTIME curtm;
::GetLocalTime(&curtm);
wsprintf(szFile, _T("%04d%02d%02d%02d%02d%02d%03d%d.eml"),
curtm.wYear,
curtm.wMonth,
curtm.wDay,
curtm.wHour,
curtm.wMinute,
curtm.wSecond,
curtm.wMilliseconds,
i);
TCHAR szFullPath[MAX_PATH + 1];
wsprintf(szFullPath, _T("%s\\%s"),
szMailBox, szFile);
IMailPtr oMail = oClient->GetMail(pInfo);
oMail->SaveAs(szFullPath, VARIANT_TRUE);
if(leaveCopy)
{
// Add the email uidl to uidl file to avoid we retrieve it next time.
uidlManager->AddUIDL(oServer, pInfo->UIDL, szFile);
}
else
{
oClient->Delete(pInfo);
// Remove UIDL from local uidl file.
uidlManager->RemoveUIDL(oServer, pInfo->UIDL);
}
}
}
catch(_com_error &ep)
{
_tprintf(_T("Error: %s"), (const TCHAR*)ep.Description());
}
//update the uidl list to a text file and then we can load it next time.
if (uidlManager != nullptr && isUidlLoaded)
{
uidlManager->Update();
}
return 0;
}
[Delphi]
unit Unit1;
interface
uses
Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
Dialogs, StdCtrls, StrUtils, EAGetMailObjLib_TLB; // Add EAGetMail unit
type
TForm1 = class(TForm)
Button1: TButton;
procedure Button1Click(Sender: TObject);
private
{ Private declarations }
public
{ Public declarations }
end;
const
MailServerPop3 = 0;
MailServerImap4 = 1;
MailServerEWS = 2;
MailServerDAV = 3;
var
Form1: TForm1;
implementation
{$R *.dfm}
procedure TForm1.Button1Click(Sender: TObject);
var
oServer: TMailServer;
oClient: TMailClient;
oTools: TTools;
oMail: IMail;
oUIDLManager: TUIDLManager;
infos: IMailInfoCollection;
oInfo: IMailInfo;
localInbox, fileName, fullFileName: WideString;
isUidlLoaded: Boolean;
leaveCopy: Boolean;
i: integer;
begin
// set current thread code page to system default code page.
SetThreadLocale(GetSystemDefaultLCID());
// leave a copy of message on server
leaveCopy := true;
isUidlLoaded := false;
// uidl is the identifier of every email on POP3/IMAP4 server, to avoid retrieve
// the same email from server more than once, we record the email uidl retrieved every time
// if you delete the email from server every time and not to leave a copy of email on
// the server, then please remove all the function about uidl.
oUIDLManager := TUIDLManager.Create(Application);
try
oTools := TTools.Create(Application);
localInbox := GetCurrentDir() + '\inbox';
oTools.CreateFolder(localInbox);
oUIDLManager.Load(localInbox + '\uidl.txt');
isUidlLoaded := true;
oServer := TMailServer.Create(Application);
oServer.Server := 'pop3.emailarchitect.net';
oServer.User := 'test@emailarchitect.net';
oServer.Password := 'testpassword';
oServer.Protocol := MailServerPop3;
// Enable SSL/TLS Connection, most modern email server require SSL/TLS connection by default.
oServer.SSLConnection := true;
// Set 995 SSL POP3 port
oServer.Port := 995;
// If your POP3 server doesn't deploy SSL connection
// Please use
// oServer.SSLConnection := false;
// oServer.Port := 110;
oClient := TMailClient.Create(Application);
oClient.LicenseCode := 'TryIt';
oClient.Connect1(oServer.DefaultInterface);
ShowMessage('Connected!');
infos := oClient.GetMailInfoList();
ShowMessage(Format('Total %d email(s)', [infos.Count]));
// Remove the local uidl that is not existed on the server,
oUIDLManager.SyncUIDLEX(oServer.DefaultInterface, infos);
oUIDLManager.Update();
for i := 0 to infos.Count - 1 do
begin
oInfo := infos.Item[i];
// This email has not been retrieved before, then get it
if oUIDLManager.FindUIDL(oServer.DefaultInterface, oInfo.UIDL) <> nil then
continue; // this email has been downloaded, do not receive it again
// Generate a random file name by current local datetime,
// You can use your method to generate the filename if you do not like it
fileName := oTools.GenFileName(i) + '.eml';
fullFileName := localInbox + '\' + fileName;
// Receive email from email server
oMail := oClient.GetMail(oInfo);
ShowMessage('From: ' + oMail.From.Address + #13#10 +
'Subject: ' + oMail.Subject);
// Save email to local disk
oMail.SaveAs(fullFileName, true);
if leaveCopy Then
begin
// Add the email uidl to uidl file to avoid we retrieve it next time.
oUIDLManager.AddUIDL(oServer.DefaultInterface, oInfo.UIDL, fileName);
end
else
begin
oClient.Delete(oInfo);
// Remove UIDL from local uidl file.
oUIDLManager.RemoveUIDL(oServer.DefaultInterface, oInfo.UIDL);
end;
end;
// Quit and expunge emails marked as deleted from email server
oClient.Quit;
except
on ep:Exception do
ShowMessage('Error: ' + ep.Message);
end;
// Update the uidl list to a text file and then we can load it next time.
if isUidlLoaded then
oUIDLManager.Update();
end;
end.
See Also
Using EAGetMail POP3 & IMAP4 ActiveX Object
Registration-free COM with Manifest File
User Authentication and SSL Connection
Enable TLS 1.2 on Windows XP/2003/2008/7/2008 R2
Using Gmail IMAP4 OAUTH
Using Gmail/GSuite Service Account + IMAP4 OAUTH
Using Office365 EWS OAUTH
Using Office365 EWS OAUTH in Background Service
Using Hotmail IMAP4 OAUTH
Digital Signature and E-mail Encryption/Decryption
Parse Bounced Email (delivery-report)
Work with winmail.dat (TNEF Parser)
EAGetMail ActiveX Object References
EAGetMail POP3 & IMAP4 Component Samples
Online Tutorials
Using UIDL Function to Mark the Email has been downloaded/read in VB6 - Tutorial
Using UIDL Function to Mark the Email has been downloaded/read in Delphi - Tutorial
Using UIDL Function to Mark the Email has been downloaded/read in VC++ - Tutorial