1smtp(n)                           smtp client                          smtp(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       smtp - Client-side tcl implementation of the smtp protocol
9

SYNOPSIS

11       package require Tcl
12
13       package require mime  ?1.5.4?
14
15       package require smtp  ?1.5?
16
17       ::smtp::sendmessage token option...
18
19______________________________________________________________________________
20

DESCRIPTION

22       The  smtp  library  package provides the client side of the Simple Mail
23       Transfer Protocol (SMTP) (1) (2).
24
25       ::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
30              -servers
31                     A list of SMTP servers. The default is localhost.
32
33                     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
40              -ports A list of SMTP ports. The default is 25.
41
42                     See option -servers above regardig the behaviour for then
43                     multiple servers and ports are specified.
44
45              -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
51              -queue Indicates  that  the SMTP server should be asked to queue
52                     the message for later processing. A boolean value.
53
54              -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
59              -originator
60                     A string containing an 822-style  address  specification.
61                     If  present  the  header isn't examined for an originator
62                     address.
63
64              -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
70              -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
75              -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
80              -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
87              -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
97              -username
98
99              -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
111                     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
115       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
123       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

AUTHENTICATION

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
136       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

EXAMPLE

141              proc send_simple_message {recipient email_server subject body} {
142                  package require smtp
143                  package require mime
144
145                  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
153              send_simple_message someone@somewhere.com localhost \
154                  "This is the subject." "This is the message."
155
156

TLS SECURITY CONSIDERATIONS

158       This package uses the TLS package to handle the security for https urls
159       and other socket connections.
160
161       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
167       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
175
176                  package require tls
177                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
178
179                  ... your own application code ...
180
181

REFERENCES

183       [1]    Jonathan B. Postel, "SIMPLE MAIL TRANSFER  PROTOCOL",  RFC  821,
184              August 1982.  (http://www.rfc-editor.org/rfc/rfc821.txt)
185
186       [2]    J.  Klensin,  "Simple  Mail  Transfer Protocol", RFC 2821, April
187              2001.  (http://www.rfc-editor.org/rfc/rfc2821.txt)
188
189       [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
193       [4]    J. Myers, "SMTP Service Extension for Authentication", RFC 2554,
194              March 1999.  (http://www.rfc-editor.org/rfc/rfc2554.txt)
195

BUGS, IDEAS, FEEDBACK

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
203       When proposing code changes, please provide unified diffs, i.e the out‐
204       put of diff -u.
205
206       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

SEE ALSO

212       ftp, http, mime, pop3
213

KEYWORDS

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

CATEGORY

219       Networking
220
222       Copyright (c) 1999-2000 Marshall T. Rose and others
223
224
225
226
227tcllib                                1.5                              smtp(n)
Impressum