1smtp(n) smtp client smtp(n)
2______________________________________________________________________________
6
8 smtp - Client-side tcl implementation of the smtp protocol
9
11 package require Tcl
12 package require mime ?1.5.4?
14 package require smtp ?1.5?
16 ::smtp::sendmessage token option...
18______________________________________________________________________________
20
22 The smtp library package provides the client side of the Simple Mail
23 Transfer Protocol (SMTP) (1) (2).
24 ::smtp::sendmessage token option...
26 This command sends the MIME part (see package mime) represented
27 by token to an SMTP server. options is a list of options and
28 their associated values. The recognized options are:
29 -servers
31 A list of SMTP servers. The default is localhost.
32 If multiple servers are specified they are tried in se‐
34 quence. Note that the -ports are iterated over in tandem
35 with the servers. If there are not enough ports for the
36 number of servers the default port (see below) is used.
37 If there are more ports than servers the superfluous
38 ports are ignored.
39 -ports A list of SMTP ports. The default is 25.
41 See option -servers above regardig the behaviour for then
43 multiple servers and ports are specified.
44 -client
46 The name to use as our hostname when connecting to the
47 server. By default this is either localhost if one of the
48 servers is localhost, or is set to the string returned by
49 info hostname.
50 -queue Indicates that the SMTP server should be asked to queue
52 the message for later processing. A boolean value.
53 -atleastone
55 Indicates that the SMTP server must find at least one re‐
56 cipient acceptable for the message to be sent. A boolean
57 value.
58 -originator
60 A string containing an 822-style address specification.
61 If present the header isn't examined for an originator
62 address.
63 -recipients
65 A string containing one or more 822-style address speci‐
66 fications. If present the header isn't examined for re‐
67 cipient addresses). If the string contains more than one
68 address they will be separated by commas.
69 -header
71 A list containing two elements, an smtp header and its
72 associated value (the -header option may occur zero or
73 more times).
74 -usetls
76 This package supports the RFC 3207 TLS extension (3) by
77 default provided the tls package is available. You can
78 turn this off with this boolean option.
79 -tlsimport
81 This boolean flag is false by default. When this flag is
82 set the package will import TLS on a sucessfully opened
83 channel. This is needed for connections using native TLS
84 negotiation instead of STARTTLS. The tls package is auto‐
85 matically required when needed.
86 -tlspolicy
88 This option lets you specify a command to be called if an
89 error occurs during TLS setup. The command is called with
90 the SMTP code and diagnostic message appended. The com‐
91 mand should return 'secure' or 'insecure' where insecure
92 will cause the package to continue on the unencrypted
93 channel. Returning 'secure' will cause the socket to be
94 closed and the next server in the -servers list to be
95 tried.
96 -username
98 -password
100 If your SMTP server requires authentication (RFC 2554
101 (4)) before accepting mail you can use -username and
102 -password to provide your authentication details to the
103 server. Currently this package supports DIGEST-MD5, CRAM-
104 MD5, LOGIN and PLAIN authentication methods. The most se‐
105 cure method will be tried first and each method tried in
106 turn until we are either authorized or we run out of
107 methods. Note that if the server permits a TLS connec‐
108 tion, then the authorization will occur after we begin
109 using the secure channel.
110 Please also read the section on Authentication, it de‐
112 tails the necessary prequisites, i.e. packages needed to
113 support these options and authentication.
114 If the -originator option is not present, the originator address is
116 taken from From (or Resent-From); similarly, if the -recipients option
117 is not present, recipient addresses are taken from To, cc, and Bcc (or
118 Resent-To, and so on). Note that the header key/values supplied by the
119 -header option (not those present in the MIME part) are consulted. Re‐
120 gardless, header key/values are added to the outgoing message as neces‐
121 sary to ensure that a valid 822-style message is sent.
122 The command returns a list indicating which recipients were unaccept‐
124 able to the SMTP server. Each element of the list is another list, con‐
125 taining the address, an SMTP error code, and a textual diagnostic. De‐
126 pending on the -atleastone option and the intended recipients, a non-
127 empty list may still indicate that the message was accepted by the
128 server.
129
131 Beware. SMTP authentication uses SASL. I.e. if the user has to authen‐
132 ticate a connection, i.e. use the options -user and -password (see
133 above) it is necessary to have the sasl package available so that smtp
134 can load it.
135 This is a soft dependency because not everybody requires authentica‐
137 tion, and sasl depends on a lot of the cryptographic (secure) hashes,
138 i.e. all of md5, otp, md4, sha1, and ripemd160.
139
141 proc send_simple_message {recipient email_server subject body} {
142 package require smtp
143 package require mime
144 set token [mime::initialize -canonical text/plain \
146 -string $body]
147 mime::setheader $token Subject $subject
148 smtp::sendmessage $token \
149 -recipients $recipient -servers $email_server
150 mime::finalize $token
151 }
152 send_simple_message someone@somewhere.com localhost \
154 "This is the subject." "This is the message."
155
158 This package uses the TLS package to handle the security for https urls
159 and other socket connections.
160 Policy decisions like the set of protocols to support and what ciphers
162 to use are not the responsibility of TLS, nor of this package itself
163 however. Such decisions are the responsibility of whichever applica‐
164 tion is using the package, and are likely influenced by the set of
165 servers the application will talk to as well.
166 For example, in light of the recent POODLE attack [http://googleonli‐
168 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
169 ssl-30.html] discovered by Google many servers will disable support for
170 the SSLv3 protocol. To handle this change the applications using TLS
171 must be patched, and not this package, nor TLS itself. Such a patch
172 may be as simple as generally activating tls1 support, as shown in the
173 example below.
174 package require tls
177 tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
178 ... your own application code ...
180
183 [1] Jonathan B. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821,
184 August 1982. (http://www.rfc-editor.org/rfc/rfc821.txt)
185 [2] J. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April
187 2001. (http://www.rfc-editor.org/rfc/rfc2821.txt)
188 [3] P. Hoffman, "SMTP Service Extension for Secure SMTP over Trans‐
190 port Layer Security", RFC 3207, February 2002. (http://www.rfc-
191 editor.org/rfc/rfc3207.txt)
192 [4] J. Myers, "SMTP Service Extension for Authentication", RFC 2554,
194 March 1999. (http://www.rfc-editor.org/rfc/rfc2554.txt)
195
197 This document, and the package it describes, will undoubtedly contain
198 bugs and other problems. Please report such in the category smtp of
199 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
200 also report any ideas for enhancements you may have for either package
201 and/or documentation.
202 When proposing code changes, please provide unified diffs, i.e the out‐
204 put of diff -u.
205 Note further that attachments are strongly preferred over inlined
207 patches. Attachments can be made by going to the Edit form of the
208 ticket immediately after its creation, and then using the left-most
209 button in the secondary navigation bar.
210
212 ftp, http, mime, pop3
213
215 email, internet, mail, mime, net, rfc 2554, rfc 2821, rfc 3207, rfc
216 821, rfc 822, smtp, tls
217
219 Networking
220
222 Copyright (c) 1999-2000 Marshall T. Rose and others
223tcllib 1.5 smtp(n)