ns_sendmail(3)

Name

ns_sendmail - Sending mail via SMTP

Table Of Contents

• Table Of Contents
• Synopsis
• Description
• COMMANDS
• CONFIGURATION
  • SMTP Server and Timeout
  • Message IDs and Encoding
  • SMTP Authentication
  • STARTTLS
  • Configuration Parameters
• ALTERNATIVES
• EXAMPLES
• See Also
• Keywords

Synopsis

Description

ns_sendmail is a procedure for sending email from a Tcl script through a remote SMTP server. It now supports character encoding of subject and body, message-id creation, quoted printable text, AUTH PLAIN and LOGIN mechanisms. It is backwards compatible.

The helper command ns_sendmail_config returns or logs the current configuration for ns_sendmail.

In the default configuration mail is sent to "localhost" on port 25. Usually, "localhost" resolves to the host where NaviServer is deployed and the running SMTP server accepts mail from the local machine.

In order to send mail directly to a specified SMTP server other than localhost some form of authentication may be required. The AUTH PLAIN and LOGIN mechanisms are supported as they are offered by most SMTP servers and easy to implement. Note, however, they are plaintext mechanisms and not secure. Also note that ns_sendmail does not verify if AUTH PLAIN or LOGIN are offered by the SMTP server at all. In case of an error the error code and message are returned.

COMMANDS

ns_sendmail -to value -from value ?-subject value? ?-body value? ?-headers value? ?-bcc value? ?-cc value?

-to Email address of recipient. To send a real name along with the address give the name and place the latter between "<" and ">" like "John Foo <j.foo@example.com>". This also applies to -from, -cc and -bcc. Can be a comma-separated string with multiple recipients.

-from Email address of sender.

-subject Subject of the mail.

-body Body of the mail.

?-headers? An ns_set of key-value pairs. The set will become part of the email header. May be left empty.

?-bcc? Email address of undisclosed recipient. Can be a comma-separated string with multiple undisclosed recipients.

?-cc? Email address of additional recipient. Can be a comma-separated string with multiple recipients.

ns_sendmail_config ?log?

Returns the current configuration that is set up in the configuration file. When the ?log? is specified, the result is written to the system log, otherwise the result is returned as a flat key value list.

CONFIGURATION

The legacy ns_sendmail command reads its configuration from the ns/sendmail section.

In earlier NaviServer versions, these parameters were configured directly in ns/parameters. This legacy location is still accepted for compatibility, but new configurations should use ns/sendmail.

The command provides basic SMTP support. STARTTLS is available only when the external Tcl package tls is installed and loadable. For new applications, prefer the external nssmtpd module where appropriate, or Tcl library based mail support with modern TLS-capable SMTP handling.

 ns_section ns/sendmail {
    ns_param smtphost          localhost
    ns_param smtpport          25
    ns_param smtptimeout       60
 
    ns_param smtplogmode       false
    ns_param smtpmsgid         false
    ns_param smtpmsgidhostname ""
 
    ns_param smtpencodingmode  false
    ns_param smtpencoding      utf-8
 
    ns_param smtpauthmode      ""
    ns_param smtpauthuser      ""
    ns_param smtpauthpassword  ""
 
    # Optional STARTTLS support, when the Tcl package "tls" is available.
    # ns_param smtpusestarttls false
    # ns_param smtpcertfile    ""
    # ns_param smtpcafile      ""
    # ns_param smtpcadir       ""
 }

ALTERNATIVES

Possible alternatives are:

• The NaviServer nssmtpd module, which provides SMTP sending/relaying and receiving support, as well as detailed logging and statistics. Sending mail is performed via ns_smtpd send. This is the preferred mail interface in OpenACS.

• The Tcl Standard Library SMTP and MIME packages.

EXAMPLES

Log current configuration to server log:

 % ns_sendmail_config log
 smtpconfiguration:
      smtphost = mail.domain.tld
      smtpport = 25
      smtptimeout = 60
      smtplogmode = false
      smtpmsgid = on
      smtpmsgidhostname = host.domain.tld
      smtpencodingmode = on
      smtpencoding = iso8859-15
      smtpauthmode = PLAIN
      smtpauthuser = account--0123
      smtpauthpassword = mysecret

Default use:

 % ns_sendmail to@example.com from@example.com "My subject" "My body"

Separate multiple recipients with a comma (to,cc,bcc):

 % ns_sendmail "to1@example.com,to2@example.com" \
 	from@example.com "My subject" "My body"

You may give real names along with email address:

 % ns_sendmail "Jo Foo <to1@example.com>,Pete Bar <to2@example.com>" \
 	from@example.com "My subject" "My body"

For cc and bcc, leave header field empty, if you don't need it anyway:

 % ns_sendmail "Jo Foo <to1@example.com>,Pete Bar <to2@example.com>" \
 	from@example.com "My subject" "My body" "" "Ben Care <bencare@example.com>"

Header field is an ns_set array:

 % set SMTP_setid [ns_set create SMTPHeaders "Reply-To" "marketing@example.com"]
 % ns_sendmail "Jo Foo <to1@example.com>,Pete Bar <to2@example.com>" \
 	from@example.com "My subject" "My body" $SMTP_setid \
 	"Ben Care <bencare@example.com>"

Use smtplogmode to not send mail but watch transaction in server log:

 % ns_sendmail "Mr. White <white@example.com>" "Mr. Black <black@example.com>" "log" "this message"
 Notice: S: Helo sock12 HELO devserver 60
 Notice: S: Mail black@example.com sock12 MAIL FROM:<black@example.com> 60
 Notice: S: Rcpt white@example.com sock12 RCPT TO:<white@example.com> 60
 Notice: S: Data sock12 DATA 60
 Notice: S: Data sock12 To: Mr. White <white@example.com>
 From: Mr. Black <black@example.com>
 Subject: log
 Date: Mon, 23 Jan 2006 09:25:22 GMT
 
 this message
 
 . 60
 Notice: S: Quit sock12 QUIT 60

See Also

admin-config-params, nsd

Keywords

NaviServer, RFC822, SMTP, configuration, mail, sendmail