If you have used EmailEngine for a while, you probably notice the abundance of different message identifiers. There's
messageId , and under the hood also a sequence identifier that all seemingly do the same thing – identify an email on an IMAP account. What gives, why so many?
The reason is 40 years of IMAP evolution with backward compatibility. Each of these identifiers carries a separate role.
id– this is the ID value you can use in EmailEngine's API requests. For example
"AAAADAAAB40". It identifies a specific message entry within a particular folder and never changes. As long as the message still exists in that folder, the
idpoints to that message. It does not identify a specific email entity. So if you move an email to another folder, the id value will change for that email. If you now try to use the old
idvalue, it will point to a non-existing entry and thus is not valid anymore, even if the message is still on the account. This identifier is actually a wrapper for the
uidvalue. It encodes folder path,
uidinto it. This is how EmailEngine can find a message based on that
idfrom the IMAP account.
uid– this is the IMAP UID identifier. It's a unique (per folder, not globally) autoincrementing integer. If you consider an IMAP folder as a separate table in MySQL, then
uidwould be the
AUTO_INCREMENTprimary key for that table. If you move a message from one folder to another and then back, the message would have a different UID than it initially had – this is because the initial UID was deleted, and UID values can not be reused, so a new one is assigned to that message. As the
idvalue embeds this value, it behaves the same way – it identifies a specific message entry. Using
idvalues is better, but both are pretty much the same. The
idversion includes slightly more information, but these two are deeply connected. You would need the
uidvalue mostly when searching messages because you can provide a UID range as part of the search query, e.g.,
"123:456"would match all messages with UID values from 123 to 456.
emailId– uniquely identifies a message entity in the email account. This is the best identifier because it does not change. If you move or copy a message, the resulting email will still have the same
emailId. So all emails with the same
emailIdare different instances of the same email. Unfortunately, this identifier requires special IMAP extensions that are only supported by a handful of IMAP servers (Gmail, Yahoo, Fastmail, and that's about it), so it is not very reliable. Unless you exclusively target Gmail accounts.
messageId– is the value from the
Message-IDheader. This is also a good value to use because it is globally unique. Unfortunately, it is a soft limit, as there is no one that could enforce the uniqueness. Nothing prevents anyone from reusing the same
Message-IDheader over and over (or not setting it at all for a message). It is still a good indicator because all legit email senders will use it properly. If it is missing, then that message is most probably spam or something suspicious. If you have seen a
messageIdbefore, then the new one is probably a copy of that previous message. Some users use
messageIdas the main identifier and drop emails without a
messageIdvalue (because these emails are usually worthless anyway).
- There’s also the sequence-number-based identifier that is otherwise heavily used in IMAP, but EmailEngine does not expose these and only uses them internally.