#pop API reference

A POP3 receive client (RFC 1939): the line-oriented status dialogue ("+OK" / "-ERR") over the net system library, with plaintext, implicit TLS, or STLS, and auth by USER / PASS, XOAUTH2, CRAM-MD5, or SCRAM-SHA-1 / SCRAM-SHA-256. Retrieved messages come back as strings, ready for the mime module to parse. Because it uses net, this module needs the default jennifer binary (jennifer-tiny has no network stack). A session is stateful: connect, then stat / sizes / retrieve / deleteMessage, then quit. fetchAll wraps the common "get every message" case. A server "-ERR" throws a catchable Error (kind "pop3").

Import with import "pop.j" as pop;. See the pop guide for prose and examples.

#Functions

#pop.connect(opts as Options)

Open a session: greet, optional STLS upgrade, then USER / PASS auth.

Parameters

• opts {Options} - the connection settings

Returns {Session} - a live authenticated session

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.count(session as Session)

Return just the number of messages waiting.

Parameters

• session {Session} - the live session

Returns {int} - the message count

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.deleteMessage(session as Session, n as int)

Mark message n for deletion (DELE); it is removed at QUIT.

Parameters

• session {Session} - the live session
• n {int} - the 1-based message number

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.fetchAll(opts as Options)

Connect, retrieve every message (without deleting), and quit.

Parameters

• opts {Options} - the connection settings

Returns {list of string} - every message as a raw string, in message order

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.noop(session as Session)

Do nothing but keep the connection alive (NOOP) - the server resets its idle timer and replies "+OK". Useful between long pauses in a session.

Parameters

• session {Session} - the live session

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.quit(session as Session)

End the session (committing any deletions) and close the connection.

Parameters

• session {Session} - the live session

#pop.reset(session as Session)

Unmark every message marked for deletion this session (RSET), so a QUIT after it deletes nothing. Use it to abort a batch of deleteMessage calls before committing.

Parameters

• session {Session} - the live session

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.retrieve(session as Session, n as int)

Fetch message n as a raw message string (RETR), ready for mime.parse.

Parameters

• session {Session} - the live session
• n {int} - the 1-based message number

Returns {string} - the raw message text

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.sizes(session as Session)

Return the octet size of each message, in message order (LIST).

Parameters

• session {Session} - the live session

Returns {list of int} - the size in octets of each message

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.stat(session as Session)

Return the mailbox message count and total size.

Parameters

• session {Session} - the live session

Returns {Stat} - the mailbox totals

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#pop.top(session as Session, n as int, lines as int)

Preview message n: its full headers plus the first lines body lines (TOP). lines = 0 fetches headers only - a cheap way to read Subject / From / Date (parse the result with mime.parse) and decide whether to retrieve the whole body. TOP is widely but not universally supported (a server lacking it answers "-ERR").

Parameters

• session {Session} - the live session
• n {int} - the 1-based message number
• lines {int} - how many leading body lines to include (0 = headers only)

Returns {string} - the header block plus the requested body lines

Throws

• {Error} - kind "pop3" on a server "-ERR" reply (or no TOP support)

#pop.uidl(session as Session)

Return the stable unique id of every message (UIDL), as MessageId {number, id} pairs in message order. Unlike the per-session message number, a UIDL id persists across sessions, so this is the key to leave-on-server / skip-seen: keep the ids you have processed, and next time retrieve only the numbers whose id is new.

Parameters

• session {Session} - the live session

Returns {list of MessageId} - the unique id of each message

Throws

• {Error} - kind "pop3" on a server "-ERR" reply (or no UIDL support)

#pop.uidlOne(session as Session, n as int)

Return the stable unique id of one message (UIDL n).

Parameters

• session {Session} - the live session
• n {int} - the 1-based message number

Returns {string} - the message's persistent unique id

Throws

• {Error} - kind "pop3" on a server "-ERR" reply

#Structs

#pop.MessageId

One message's UIDL entry: its message number and its server-assigned unique id. The id is stable across sessions (unlike the number, which is per-session), so it is the key for "download only what is new": remember the ids you have seen, and on the next connection retrieve only the numbers whose id is new.

#pop.Options

Connection settings. security is "none", "tls" (implicit TLS on connect, port 995), or "starttls" (STLS upgrade on port 110). auth is "" (USER / PASS) or "xoauth2" (SASL bearer token, where pass holds the access token).

#pop.Session

A live POP3 session over one connection.

#pop.Stat

Mailbox totals from STAT.