pop3(3tcl)

📦
version 2.0 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💌 pop3 — the Tcl POP3 Client Library (aka pop3(3tcl) bestie edition) 🎀

okay so you want to talk to a POP3 email server from Tcl? say less. this is the whole pop3 manual page and i'm gonna walk you through it like we're texting. every flag, every default, every little detail — it's all here, no cap. 💅

✨ NAME ✨

pop3 — Tcl client for POP3 email protocol

like. that's the whole vibe. it's a client. for POP3. written in Tcl. iconic.

🌸 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

that's the whole cast of characters bestie. they all take a chan (that channel handle ::pop3::open hands you back) and they all do their little thing. 🫶

💖 DESCRIPTION 💖

the pop3 package is a simple, Tcl-only client library for the POP3 email protocol — the one spec'd out in RFC 1939 [http://www.rfc-editor.org/rfc/rfc1939.txt]. 💌

how does it work? so simple. it opens the standard POP3 socket on the server, transmits the username and password, and then hands you a Tcl API to poke at the POP3 protocol commands. that's it. that's the whole magic trick.

ok important thing: all server errors are returned as Tcl errors (thrown) and you must catch them with the Tcl catch command. no silent failures here, she will let you know. 😭

🔐 TLS SECURITY CONSIDERATIONS 🔐

this package uses the TLS package to handle the security for https urls and other socket connections. slay.

but listen — policy decisions like which protocols to support and what ciphers to use? those are not the responsibility of TLS, and definitely not of this package either. nope. those decisions belong to whichever application is using the package, and they're probably gonna be influenced by the set of servers that app is gonna talk to. it's giving "know your audience." 💅

for example — in light of the recent POODLE attack [http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html] discovered by Google, many servers will disable support for the SSLv3 protocol. to handle this change, the applications using TLS must be patched — not this package, and not TLS itself. such a patch may be as simple as generally activating tls1 support, as shown in the example below. 🦋

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

... your own application code ...

🌈 API 🌈

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

open a socket connection to the server specified by host, and transmit the username and password as login info to the server. 🫶

the default port number is 110, which you can override with the optional port argument. the return value is a channel, and every single other ::pop3 function uses that channel. she's the main character and everyone else is just supporting cast. 👑

the command recognizes three options:

  • -msex boolean — setting this option tells the package that the server we're talking to is an MS Exchange server (which has some oddities we have to work around 🙈). the default is False.
  • -retr-mode retr|list|slow — the retrieval mode determines how exactly messages are read from the server. allowed values are retr, list and slow. the default is retr. see ::pop3::retrieve for more info. 👀
  • -socketcmd cmdprefix — this option lets you override the use of the builtin socket command with any API-compatible command. the envisioned main use is securing the new connection via SSL, through specifying the command tls::socket. this command is specially recognized as well, changing the default port of the connection to 995. 🔒
  • -stls boolean — setting this option tells the package to secure the connection using SSL or TLS. it performs STARTTLS as described in IETF RFC 2595 — first it opens a normal, unencrypted connection, and then it negotiates a SSLv3 or TLSv1 connection. if the connection cannot be secured, the connection will be closed and an error will be returned. no half-secured situations, periodt. 💅
  • -tls-callback stls-callback-command — this option lets you override the tls::callback used during the -stls SSL/TLS handshake. see the TLS manual for details on how to implement this callback. 📖

💫 ::pop3::config chan

returns the configuration of the pop3 connection identified by the channel handle chan as a serialized array. it's like a little snapshot of the whole setup. 📸

💫 ::pop3::status chan

query the server for the status of the mail spool. the status is returned as a list containing two elements:

  1. the number of email messages on the server 🍓
  2. the size (in octets, 8 bit blocks) of the entire mail spool

💫 ::pop3::last chan

query 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. 😳

heads up bestie: this command may not be supported by the email server, in which case the server may return 0 or an error. not every server is emotionally available like that. 💀

💫 ::pop3::retrieve chan startIndex ?endIndex?

retrieve a range of messages from the server. if endIndex is not specified, only one message will be retrieved. the return value is a list containing each message as a separate element. see the startIndex and endIndex descriptions below. 💖

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

  • mode retr assumes that the RETR command delivers the size of the message as part of the command status and uses this to read the message efficiently. ✨
  • mode list — RETR does not deliver the size, but the LIST command does, and we use this to retrieve the message size before the actual retrieval, which can then be done efficiently. 🦋
  • the last mode, slow — the system is unable to obtain the size of the message to retrieve in any manner and falls back to reading the message from the server line by line. it's giving snail mail but we love her anyway. 🐌

it should also be noted that the system checks upon the configured mode and falls back to the slower modes if the above assumptions are not true. she adapts. she's resilient. 💅

💫 ::pop3::delete chan startIndex ?endIndex?

delete a range of messages from the server. if endIndex is not specified, only one message will be deleted. 💀

ngl important: the indices are not reordered on the server, so if you delete message 1, then the first message in the queue is message 2 (message index 1 is no longer valid). the numbering does NOT shift up to fill the gap, bestie. remember that.

see the startIndex and endIndex descriptions below. 👇

startIndex

the startIndex may be an index of a specific message starting with the index 1, or it may have any of the following values:

  • start — this is 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 to retrieve 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 an index of a specific message starting with the index "1", or it may have any of the following 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 only for that message is returned. targeted. specific. we love a queen who knows what she wants. 💅

💫 ::pop3::top chan msg n

optional POP3 command — not all servers may support this. 😭

::pop3::top retrieves headers of a message, specified by the parameter msg, and number of 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 only for 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 close the connection after sending a POP3 QUIT command down the socket. so polite. so classy. say bye with your chest. 👋

🔒 SECURE MAIL TRANSFER 🔒

a pop3 connection can be secured with SSL/TLS by requiring the package TLS and then using either the option -socketcmd or the option -stls of the command pop3::open. two paths, same destination. choose your fighter. ✨

method one — the -socketcmd way 🌸

the first method, option -socketcmd, will force the use of the tls::socket command when opening the connection. this is suitable for POP3 servers which expect SSL connections only. these will generally be 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 — the -stls way 🦋

the second method, option -stls, will connect to the standard POP3 port and then perform an STARTTLS handshake. this will only work for POP3 servers which have this capability. the package will confirm that the server supports STARTTLS and the handshake was performed correctly before proceeding with authentication. she checks her work, bestie. 💅

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

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

...

to be continued... 🌈 (more parts incoming, don't go anywhere bestie) 🫶

🐛 BUGS, IDEAS, FEEDBACK 🐛

okay bestie, real talk 💖 — this doc? and the whole package it's describing? yeah, they will undoubtedly have bugs and other problems. not being dramatic, that's just literally what the page says. nothing is perfect, not even your fave.

so if you spot something cursed, please report it under the category pop3 in the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

and if you've got big brain ideas for enhancements — for the package, for the docs, for literally either one — send those in too. we want them 🫶

💅 one (1) thing about code changes

when you're proposing code changes, please bring unified diffs, i.e. the output of:

diff -u

no vibes-based handwaving, give us the diff ✨

📎 and about patches, bestie

attachments are strongly preferred over inlined patches. like, strongly. not a drill.

how do you attach one? it's a whole little side quest but it's easy:

  1. go to the Edit form of the ticket — immediately after its creation, don't wander off
  2. then use the left-most button in the secondary navigation bar

and that's it, you're an icon 👑

🔑 KEYWORDS 🔑

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

iykyk 🌸

🗂 CATEGORY 🗂

Networking 🌈

and that's the whole page, bestie!! 🎀 this was the pop3(3tcl) manpage from tcllib 1.11 — go forth and fetch your mail securely, mwah 💖✨🦋

📦 where this page comes from