smtp(n)

💌 NAME

okay bestie, meet smtp — it's the client-side Tcl implementation of the SMTP protocol, i.e. the part that sends the mail (the smtp(n) manual page, for the record 💅).

---

✨ SYNOPSIS ✨

package require Tcl

package require mime ?1.5.4?

package require smtp ?1.5.2?

::smtp::sendmessage token option...

---

🦋 DESCRIPTION 🦋

The smtp library package gives you the client side of the Simple Mail Transfer Protocol, aka SMTP — and yes it cites its receipts, that's (1) (2) up there in the references 🫶.

💫 ::smtp::sendmessage token option...

This command sends the MIME part (see package mime) that token represents over to an SMTP server. options is a list of options and their associated values — classic pair-up situation, main character energy ✨.

The recognized options are, and yes we're doing all of them, no skipping:

• -servers — a list of SMTP servers. Default is localhost. If you hand over multiple servers they get tried in sequence, one after another. Heads up though: the -ports are iterated over in tandem with the servers. If there aren't enough ports to go around for all the servers, the default port (peep below 👇) gets used. If there are more ports than servers, the extra ports are just ignored, no harm no foul.
• -ports — a list of SMTP ports. Default is 25. For what happens when you've got multiple servers and ports going at once, go read the -servers bullet above, it's the same vibe.
• -client — the name to use as our hostname when connecting to the server. By default this is either localhost if one of the servers is localhost, or it's set to the string returned by info hostname.
• -queue — tells the SMTP server to please queue the message for later processing. A boolean value, so true/false energy.
• -atleastone — insists that the SMTP server find at least one acceptable recipient before the message counts as sent. A boolean value. Very "at least one of you has to show up to the party" of it.
• -originator — a string holding an 822-style address specification. If it's present, the header is not examined for an originator address. No cap.
• -recipients — a string with one or more 822-style address specifications. If it's present, the header is not examined for recipient addresses. If the string has more than one address, they get separated by commas.
• -header — a list containing two elements: an smtp header and its associated value. This one can show up zero or more times (it's the repeat offender of the options, respectfully 🙈).
• -usetls — this package supports the RFC 3207 TLS extension (3) by default, provided the tls package is available. You can turn that off with this boolean option.
• -tlsimport — this boolean flag is false by default. When it's set, the package will import TLS on a successfully opened channel. You need this for connections using native TLS negotiation instead of STARTTLS. The tls package gets automatically required whenever it's needed.
• -tlspolicy — lets you specify a command to be called if an error happens during TLS setup. That command gets called with the SMTP code and diagnostic message appended to it. It should return 'secure' or 'insecure' — where insecure makes the package carry on over the unencrypted channel. Returning 'secure' closes the socket and moves on to the next server in the -servers list.
• -username — if your SMTP server requires authentication (RFC 2554 (4)) before it'll accept mail, you can use -username and -password to hand your authentication details over to the server. Currently this package supports DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN authentication methods. The most secure method gets tried first, and then each method is tried in turn until you're either authorized or you run out of methods. Note that if the server permits a TLS connection, the authorization happens after we start using the secure channel. Also please read the section on Authentication — it lays out the necessary prerequisites, i.e. which packages you need to support these options and this authentication. 💖
• -password — the other half of that pair, same rules as -username right above 👆 (server needs auth, DIGEST-MD5 / CRAM-MD5 / LOGIN / PLAIN, most secure first, secure channel first if TLS is allowed, and go read the Authentication section).

If the -originator option isn't present, the originator address is taken from From (or Resent-From). Same deal for -recipients: if it's not present, recipient addresses get taken from To, cc, and Bcc (or Resent-To, and so on). Note that it's the header key/values supplied by the -header option that get consulted — not the ones present in the MIME part. Regardless of all that, header key/values get added to the outgoing message as necessary to make sure a valid 822-style message is actually sent.

The command returns a list showing which recipients were unacceptable to the SMTP server. Each element of that list is another list, containing the address, an SMTP error code, and a textual diagnostic. Depending on the -atleastone option and who you meant to send to, a non-empty list can still mean the message was accepted by the server. Iconic, honestly.

---

🔐 AUTHENTICATION 🔐

Beware. SMTP authentication uses SASL. So if the user has to authenticate a connection, i.e. use the options -user and -password (see above), it is necessary to have the sasl package available so that smtp can load it.

This is a soft dependency, because not everybody requires authentication, and sasl depends on a whole lot of the cryptographic (secure) hashes — i.e. all of md5, otp, md4, sha1, and ripemd160. That's a lot of besties to bring to the function, lowkey.

---

🌸 EXAMPLE 🌸

proc send_simple_message {recipient email_server subject body} {
    package require smtp
    package require mime

    set token [mime::initialize -canonical text/plain \
  -string $body]
    mime::setheader $token Subject $subject
    smtp::sendmessage $token \
  -recipients $recipient -servers $email_server
    mime::finalize $token
}

send_simple_message someone@somewhere.com localhost \
    "This is the subject." "This is the message."

---

🛡️ TLS SECURITY CONSIDERATIONS 🛡️

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

Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of TLS, nor of this package itself, however. Those calls belong to whichever application is using the package, and they're probably influenced by the set of servers that application will be talking to as well.

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 that change, the applications using TLS have to be patched — not this package, and not TLS itself. Such a patch may be as simple as generally activating tls1 support, like in the example below 👇

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

... your own application code ...

---

📚 REFERENCES 📚

1. Jonathan B. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821, August 1982. (http://www.rfc-editor.org/rfc/rfc821.txt)
2. J. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April 2001. (http://www.rfc-editor.org/rfc/rfc2821.txt)
3. P. Hoffman, "SMTP Service Extension for Secure SMTP over Transport Layer Security", RFC 3207, February 2002. (http://www.rfc-editor.org/rfc/rfc3207.txt)
4. J. Myers, "SMTP Service Extension for Authentication", RFC 2554, March 1999. (http://www.rfc-editor.org/rfc/rfc2554.txt)

---

🐛 BUGS, IDEAS, FEEDBACK 🐛

This document, and the package it describes, will undoubtedly contain bugs and other problems (not me being dramatic, it's in writing 😭). Please report them in the category smtp of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. Please also report any ideas for enhancements you may have for either the package and/or the documentation — we want them fr fr.

When proposing code changes, please provide unified diffs, i.e. the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. Slay.

---

👀 SEE ALSO 👀

ftp, http, mime, pop3

---

🔑 KEYWORDS 🔑

email, internet, mail, mime, net, rfc 2554, rfc 2821, rfc 3207, rfc 821, rfc 822, smtp, tls

---

🗂️ CATEGORY 🗂️

Networking

---

©️ COPYRIGHT ©️

Copyright (c) 1999-2000 Marshall T. Rose and others

---

and that's the whole thing bestie 🫶 this page comes to you from tcllib 1.5.2 (the smtp(n) manual, version 1.5.2 energy), so go send some mail, stay secure, and don't forget the SASL. periodt 💅✨