pop3(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 pop3 💖

okay so this is the manual page for the pop3 package — that's the Tcl POP3 Client Library, and yes bestie, it's giving "your email, but make it Tcl" ✨

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require pop3 ?1.11?

::pop3::open   ?-msex   0|1?   ?-retr-mode  retr|list|slow?  ?-socketcmd
cmdprefix?  ?-stls  0|1?  ?-tls-callback   stls-callback-command?   host
username password ?port?

::pop3::config chan

::pop3::status chan

::pop3::last chan

::pop3::retrieve chan startIndex ?endIndex?

::pop3::delete chan startIndex ?endIndex?

::pop3::list chan ?msg?

::pop3::top chan msg n

::pop3::uidl chan ?msg?

::pop3::capa chan

::pop3::close chan

🦋 DESCRIPTION 🦋

So the pop3 package hands you a cute lil' Tcl-only client library for the POP3 email protocol, exactly as it's spelled out in RFC 1939 — that's http://www.rfc-editor.org/rfc/rfc1939.txt if you wanna read the whole thing, no cap.

How does it work? It opens the standard POP3 socket on the server, sends your username and password over, and then gives you a whole Tcl API so you can talk to the POP3 protocol commands directly. main character energy fr 💅

Heads up bestie: every single server error comes back as a Tcl error (thrown), which you must catch with the Tcl catch command. No sneaky silent failures here, she will absolutely tell you. 😭

🔒 TLS SECURITY CONSIDERATIONS 🔒

This package uses the TLS package to handle the security for https urls and other socket connections. secure queen behavior 🔐

But here's the tea: policy decisions — like which protocols to support and which ciphers to use — are not the responsibility of TLS, and they're not this package's job either. Those calls belong to whichever application is using the package, and they're probably gonna be influenced by the set of servers that application is gonna talk to. iykyk.

For example, in light of the recent POODLE attack (http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html) that Google discovered, a lot of servers are disabling support for the SSLv3 protocol. And to handle that change, it's the applications using TLS that have to get patched — not this package, and not TLS itself. That patch might be as simple as generally activating tls1 support, like this:

package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol

... your own application code ...

👑 API 👑

`::pop3::open`

::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd cmdprefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host username password ?port?

Opens a socket connection to the server you named in host, then transmits the username and password as login info to the server. The default port number is 110, and you can override that with the optional port argument. What you get back is a channel — and that channel is what all the other ::pop3 functions are gonna use. 🎀

The command recognizes three options:

-msex boolean — setting this tells the package that the server we're chatting with is an MS Exchange server (which has some oddities we have to work around, smh). The default is False.
-retr-mode retr|list|slow — the retrieval mode decides how exactly messages get read off the server. Allowed values are retr, list and slow. The default is retr. Peep ::pop3::retrieve for more info.
-socketcmd cmdprefix — this one lets you override the use of the builtin socket command with any API-compatible command. The main envisioned use is securing the new connection via SSL, by specifying the command tls::socket. That command is specially recognized too, and it changes the default port of the connection to 995. 👀
-stls boolean — setting this tells the package to secure the connection using SSL or TLS. It performs STARTTLS as described in IETF RFC 2595: it first opens a normal, unencrypted connection, and then negotiates a SSLv3 or TLSv1 connection. If the connection can't be secured, the connection will be closed and an error will be returned.
-tls-callback stls-callback-command — this lets you override the tls::callback used during the -stls SSL/TLS handshake. Go read the TLS manual for the deets on how to implement this callback. 📖

ngl the original text says "three options" and then lists five, and we are simply not gonna stress about it. all five are real, all five are here. periodt. 💅

`::pop3::config chan`

Returns the configuration of the pop3 connection identified by the channel handle chan, as a serialized array.

`::pop3::status chan`

Queries the server for the status of the mail spool. The status comes back as a list with two elements: the first is the number of email messages on the server, and the second is the size (in octets, 8 bit blocks) of the entire mail spool. 🍓

`::pop3::last chan`

Queries the server for the last email message read from the spool. This value includes all messages read from all clients connecting to the login account. Fair warning: this command may not be supported by the email server — and in that case, the server might return 0 or just an error. 🙈

`::pop3::retrieve chan startIndex ?endIndex?`

Retrieves a range of messages from the server. If endIndex isn't specified, only one message gets retrieved. The return value is a list containing each message as a separate element. Scroll down for the startIndex and endIndex descriptions.

The retrieval mode determines how exactly messages are read from the server:

mode retr assumes the RETR command delivers the size of the message as part of the command status, and uses that to read the message efficiently.
mode list — RETR doesn't deliver the size, but the LIST command does, so we use that to grab the message size before the actual retrieval, which can then be done efficiently.
the last mode, slow, is for when the system is unable to obtain the size of the message in any manner whatsoever, and it falls back to reading the message from the server line by line. 🐌

Also worth noting: the system checks on the configured mode and falls back to the slower modes if those assumptions above turn out not to be true. she adapts. 💁

`::pop3::delete chan startIndex ?endIndex?`

Deletes a range of messages from the server. If endIndex isn't specified, only one message gets deleted. And listen — the indices are not reordered on the server, so if you delete message 1, then the first message in the queue becomes message 2 (message index 1 is no longer valid). 💀 See the startIndex and endIndex descriptions below.

startIndex — the startIndex may be the index of a specific message starting with the index 1, or it can have any of these values:
- start — a logical value for the first message in the spool, equivalent to the value 1.
- next — the message immediately following the last message read, see ::pop3::last.
- end — the most recent message in the spool (the end of the spool). This is useful for retrieving only the most recent message. ✨
endIndex — the endIndex is an optional parameter and defaults to the value -1, which indicates to only retrieve the one message specified by startIndex. If specified, it may be the index of a specific message starting with the index 1, or it may have any of these values:
- last — the message is the last message read by a POP3 client, see ::pop3::last.
- end — the most recent message in the spool (the end of the spool).

`::pop3::list chan ?msg?`

Returns the scan listing of the mailbox. If the parameter msg is given, then the listing for only that message is returned. 🧚

`::pop3::top chan msg n`

Optional POP3 command — not all servers may support this. ::pop3::top retrieves the headers of a message, specified by parameter msg, plus n lines from the message body.

`::pop3::uidl chan ?msg?`

Optional POP3 command — not all servers may support this. ::pop3::uidl returns the uid listing of the mailbox. If the parameter msg is specified, then the listing for only that message is returned.

`::pop3::capa chan`

Optional POP3 command — not all servers may support this. ::pop3::capa returns a list of the capabilities of the server. TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities. See IETF RFC 2449. 🔥

`::pop3::close chan`

Gracefully closes the connection after sending a POP3 QUIT command down the socket. bye bestie, it was real 🫶

🎀 SECURE MAIL TRANSFER 🎀

A pop3 connection can be secured with SSL/TLS by requiring the TLS package and then using either the option -socketcmd or the option -stls of the command pop3::open.

Method one: option -socketcmd will force the use of the tls::socket command when opening the connection. This is suitable for POP3 servers that expect SSL connections only — those are generally listening on port 995. 🌈

package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...

# Create secured pop3 channel
pop3::open -socketcmd tls::socket \
   $thehost $theuser $thepassword

...

Method two: option -stls will connect to the standard POP3 port and then perform a STARTTLS handshake. This only works for POP3 servers that have this capability. The package will confirm that the server supports STARTTLS and that the handshake was performed correctly before it proceeds with authentication. 👑

package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...

# Create secured pop3 channel
pop3::open -stls 1 \
   $thehost $theuser $thepassword

...

🐛 BUGS, IDEAS, FEEDBACK 🐛

okay bestie, real talk for a sec 💖 this doc — and the whole package it describes — will undoubtedly have bugs and other problems in it. not "maybe", not "hypothetically", it's giving guaranteed. so if you spot one, pls don't just suffer in silence 😭

report bugs in the category pop3 of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist
also send any ideas for enhancements you have for either the package and/or the documentation 🫶

like, if you've been sitting on a glow-up idea for this thing, the maintainers wanna hear it fr fr ✨

🛠️ when you're proposing code changes

okay so this part matters, don't skip it 🙈 when you propose code changes, please provide unified diffs, i.e. the output of diff -u.

not me begging you to actually use the right format 💀 a raw diff dump is a whole vibe killer.

also, note further that attachments are strongly preferred over inlined patches. periodt.

how do you even attach stuff?? so glad you asked 🎀:

go to the Edit form of the ticket immediately after its creation
then use the left-most button in the secondary navigation bar

and boom, attachment achieved 💅

🔑 KEYWORDS 🔑

email, mail, pop, pop3, rfc 1939, secure, ssl, tls

iykyk 🌸

📂 CATEGORY 📂

Networking

that's the whole page bestie, you made it to the end and honestly? iconic 👑 this one's from tcllib, version 1.11, for pop3(n) — go forth and pop those mails securely, mwah 💖🦋

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms