1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin smtp n 1.4.5] 3[copyright {1999-2000 Marshall T. Rose and others}] 4[moddesc {smtp client}] 5[titledesc {Client-side tcl implementation of the smtp protocol}] 6[category Networking] 7[require Tcl] 8[require mime [opt 1.5.4]] 9[require smtp [opt 1.4.5]] 10[description] 11[para] 12 13The [package smtp] library package provides the client side of the 14Simple Mail Transfer Protocol (SMTP) (1) (2). 15 16[list_begin definitions] 17 18[call [cmd ::smtp::sendmessage] [arg token] [arg option]...] 19 20This command sends the MIME part (see package [package mime]) 21represented by [arg token] to an SMTP server. [arg options] is a list 22of options and their associated values. The recognized options are: 23 24[list_begin definitions] 25 26[def [option -servers]] 27 28A list of SMTP servers. The default is [const localhost]. 29 30[def [option -ports]] 31 32A list of SMTP ports. The default is [const 25]. 33 34[def [option -client]] 35 36The name to use as our hostname when connecting to the server. By 37default this is either localhost if one of the servers is localhost, 38or is set to the string returned by [cmd "info hostname"]. 39 40[def [option -queue]] 41 42Indicates that the SMTP server should be asked to queue the message 43for later processing. A boolean value. 44 45[def [option -atleastone]] 46 47Indicates that the SMTP server must find at least one recipient 48acceptable for the message to be sent. A boolean value. 49 50[def [option -originator]] 51 52A string containing an 822-style address specification. If present the 53header isn't examined for an originator address. 54 55[def [option -recipients]] 56 57A string containing one or more 822-style address specifications. If 58present the header isn't examined for recipient addresses). If the 59string contains more than one address they will be separated by 60commas. 61 62[def [option -header]] 63 64A list containing two elements, an smtp header and its associated 65value (the -header option may occur zero or more times). 66 67[def [option -usetls]] 68 69This package supports the RFC 3207 TLS extension (3) by default provided the 70tls package is available. You can turn this off with this boolean option. 71 72[def [option -tlspolicy]] 73 74This option lets you specify a command to be called if an error occurs 75during TLS setup. The command is called with the SMTP code and diagnostic 76message appended. The command should return 'secure' or 'insecure' where 77insecure will cause the package to continue on the unencrypted channel. 78Returning 'secure' will cause the socket to be closed and the next server 79in the [option -servers] list to be tried. 80 81[def [option -username]] 82[def [option -password]] 83 84If your SMTP server requires authentication (RFC 2554 (4)) before 85accepting mail you can use [option -username] and [option -password] 86to provide your authentication details to the server. Currently this 87package supports DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN authentication 88methods. The most secure method will be tried first and each method 89tried in turn until we are either authorized or we run out of 90methods. Note that if the server permits a TLS connection, then the 91authorization will occur after we begin using the secure channel. 92 93[list_end] 94[para] 95 96If the [option -originator] option is not present, the originator 97address is taken from [const From] (or [const Resent-From]); 98similarly, if the [option -recipients] option is not present, 99recipient addresses are taken from [const To], [const cc], and 100[const Bcc] (or [const Resent-To], and so on). Note that the header 101key/values supplied by the [option -header] option (not those present 102in the MIME part) are consulted. Regardless, header key/values are 103added to the outgoing message as necessary to ensure that a valid 104822-style message is sent. 105 106[para] 107 108The command returns a list indicating which recipients were 109unacceptable to the SMTP server. Each element of the list is another 110list, containing the address, an SMTP error code, and a textual 111diagnostic. Depending on the [option -atleastone] option and the 112intended recipients, a non-empty list may still indicate that the 113message was accepted by the server. 114 115[list_end] 116 117[section EXAMPLE] 118 119[example { 120proc send_simple_message {recipient email_server subject body} { 121 package require smtp 122 package require mime 123 124 set token [mime::initialize -canonical text/plain \\ 125 -string $body] 126 mime::setheader $token Subject $subject 127 smtp::sendmessage $token \\ 128 -recipients $recipient -servers $email_server 129 mime::finalize $token 130} 131 132send_simple_message someone@somewhere.com localhost \\ 133 "This is the subject." "This is the message." 134}] 135 136[section {REFERENCES}] 137 138[list_begin enumerated] 139 140[enum] 141 Jonathan B. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821, August 1982. 142 ([uri http://www.rfc-editor.org/rfc/rfc821.txt]) 143 144[enum] 145 J. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April 2001. 146 ([uri http://www.rfc-editor.org/rfc/rfc2821.txt]) 147 148[enum] 149 P. Hoffman, "SMTP Service Extension for Secure SMTP over Transport 150 Layer Security", RFC 3207, February 2002. 151 ([uri http://www.rfc-editor.org/rfc/rfc3207.txt]) 152 153[enum] 154 J. Myers, "SMTP Service Extension for Authentication", 155 RFC 2554, March 1999. 156 ([uri http://www.rfc-editor.org/rfc/rfc2554.txt]) 157 158[list_end] 159 160[section {BUGS, IDEAS, FEEDBACK}] 161 162This document, and the package it describes, will undoubtedly contain 163bugs and other problems. 164 165Please report such in the category [emph smtp] of the 166[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 167 168Please also report any ideas for enhancements you may have for either 169package and/or documentation. 170 171 172[see_also mime pop3 ftp http] 173[keywords mail mail email smtp mime tls \ 174 {rfc 821} {rfc 822} {rfc 2821} {rfc 3207} {rfc 2554} internet net] 175[manpage_end] 176