IMAP · Internet Message Access Protocol

Mail that stays on the server and syncs everywhere.

12 · Application · TCP 143 / 993

IMAP

Internet Message Access Protocol

Mail that stays on the server and syncs everywhere.

LearnProtocolTier 2 · MechanismsUnderstand10 minInfrastructure

You will be able to: trace a IMAP exchange and decode it byte by byte.

Prove it: Ray Serve Distributed Actor Deployment

System design›Protocols

Study with AI
ClaudeChatGPTGeminiPerplexityMore

Part 1 of 5

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.

Part 2 of 5

Question

What this lesson prepares you to answer. Keep these in mind while you watch the packets.

2.1Target questions

  1. How is IMAP different from POP3?
  2. What does IDLE do?

The answers are in part 4.

Part 3 of 5

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.

Client
Server
* OK ready
a001 LOGIN
a002 SELECT INBOX
* 3 EXISTS, a002 OK
a003 FETCH 1 (BODY[HEADER])
Step 1 of 5

Untagged greeting.

← BackPlayNext →

3.2Decode it byte by byte

Click any byte or row. Each colour is one field.

Session

IMAP on port 143 (993 with TLS) keeps mail on the server. Each command has a tag so replies can be matched.

00002a204f4b20494d415034726576312072* OK IMAP4rev1 r
0010656164790d0a61303031204c4f47494eeady··a001 LOGIN
002020626f62202a2a2a2a2a2a2a2a0d0a61 bob ********··a
0030303031204f4b204c4f47494e20636f6d001 OK LOGIN com
0040706c657465640d0a613030322053454cpleted··a002 SEL
005045435420494e424f580d0a2a20332045ECT INBOX··* 3 E
006058495354530d0a613030332046455443XISTS··a003 FETC
00704820312028464c41475320424f44595bH 1 (FLAGS BODY[
00804845414445525d290d0a61303034204cHEADER])··a004 L
00904f474f55540d0aOGOUT··
FieldGreeting
Length22 bytes
Text* OK IMAP4rev1 ready␍␊

Untagged lines start with *.

FieldOffsetBytesHex
Greeting0222a 20 4f 4b 20 49 4d 41 …
LOGIN222561 30 30 31 20 4c 4f 47 …
Tagged reply472561 30 30 31 20 4f 4b 20 …
SELECT721961 30 30 32 20 53 45 4c …
Untagged data91122a 20 33 20 45 58 49 53 54 53 0d 0a
FETCH1033561 30 30 33 20 46 45 54 …
LOGOUT1381361 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.

imap.tsTypeScriptCopy
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}
32 linesUTF-8TypeScript
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.

Part 4 of 5

Q&A

Check your understanding. Answer out loud, then open.

4.1Check yourself

How is IMAP different from POP3?
IMAP keeps state on the server and supports several clients, folders and flags. POP3 mostly downloads and deletes.
What does IDLE do?
It lets the server notify the client of changes without polling.
Part 5 of 5

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.
← POP3Mark as understoodFTP →