IMAP
Internet Message Access Protocol
Mail that stays on the server and syncs everywhere.
System design›Protocols
Basics
What the protocol is for, and the ideas it is built on.
1.1What it does
The protocol in plain words, before any bytes.
IMAP keeps messages on the server and lets many clients see the same mailbox: folders, read flags, drafts and searches stay in sync. Clients fetch only what they need, such as headers first, then the body when you open a message.
Commands carry a tag so several can be in flight. The server answers each with a tagged result and may send untagged updates at any time.
1.2Key ideas
The handful of ideas everything else follows from.
Tags
A client can send several commands without waiting; the tags match replies to commands.
IDLE
Holds a connection open so the server can push “new mail” in real time.
UIDs
Stable message identifiers let a client resume sync after reconnecting.
Partial fetch
Download only part of a large message.
Question
What this lesson prepares you to answer. Keep these in mind while you watch the packets.
2.1Target questions
- How is IMAP different from POP3?
- What does IDLE do?
The answers are in part 4.
Detailed answer
Watch a real exchange step by step, then take each message apart field by field.
3.1Follow the packets
Step through the exchange between the two sides.
Untagged greeting.
3.2Decode it byte by byte
Click any byte or row. Each colour is one field.
IMAP on port 143 (993 with TLS) keeps mail on the server. Each command has a tag so replies can be matched.
Untagged lines start with *.
| Field | Offset | Bytes | Hex | |
|---|---|---|---|---|
| Greeting | 0 | 22 | 2a 20 4f 4b 20 49 4d 41 … | |
| LOGIN | 22 | 25 | 61 30 30 31 20 4c 4f 47 … | |
| Tagged reply | 47 | 25 | 61 30 30 31 20 4f 4b 20 … | |
| SELECT | 72 | 19 | 61 30 30 32 20 53 45 4c … | |
| Untagged data | 91 | 12 | 2a 20 33 20 45 58 49 53 54 53 0d 0a | |
| FETCH | 103 | 35 | 61 30 30 33 20 46 45 54 … | |
| LOGOUT | 138 | 13 | 61 30 30 34 20 4c 4f 47 … |
3.3Decode it in code
A small decoder, tested against the exact bytes shown above.
Matching IMAP replies to commands
Tags let several commands run at once on one connection.
1/** Every command carries a tag. "*" lines are data, and the final line repeats the tag. */2export function parseImapLine(line: string) {3 const [tag, status, ...rest] = line.trimEnd().split(" ");4 return tag === "*"5 ? { kind: "untagged" as const, tag, data: [status, ...rest].join(" ") }6 : { kind: "tagged" as const, tag, status, data: rest.join(" ") };7}8 9/** Lets many commands run at once: replies find their command by tag. */10export class Session {11 private next = 1;12 private waiting = new Map<string, { command: string; data: string[] }>();13 private untagged: string[] = [];14 15 send(command: string): string {16 const tag = "a" + String(this.next++).padStart(3, "0");17 this.waiting.set(tag, { command, data: [] });18 return `${tag} ${command}\r\n`;19 }20 21 receive(line: string): { tag: string; status: string; data: string[] } | null {22 const p = parseImapLine(line);23 if (p.kind === "untagged") {24 this.untagged.push(p.data);25 return null;26 }27 this.waiting.delete(p.tag);28 const data = this.untagged;29 this.untagged = [];30 return { tag: p.tag, status: p.status, data };31 }32}tag === "*"- Untagged lines are data, and they can arrive at any time.
"a" + String(this.next++)- Each command gets a unique tag.
this.untagged = []- The tagged reply ends that command, and collects the data that came with it.
Tested by npm run test:modules.
Q&A
Check your understanding. Answer out loud, then open.
4.1Check yourself
How is IMAP different from POP3?
What does IDLE do?
Extra depth
The mistakes people make with this protocol in real systems.
5.1Watch out for
- Large mailboxes need careful sync strategies, or logins become slow.
- Server-side search is powerful but server dependent.
- Some servers limit simultaneous connections per account.