82
UTL_SMTP

UTL_SMTP is designed for sending e-mail over Simple Mail Transfer Protocol (SMTP). It does not have the functionality to implement an SMTP server for mail clients to send e-mail using SMTP.

Many interfaces to the SMTP package appear as both a function and a procedure. The functional form returns the reply from the server for processing by the client. The procedural form discards the reply but raises an exception if the reply indicates a transient (400-range reply code) or permanent error (500-range reply code).

Note that the original SMTP protocol communicates using 7-bit ASCII. Using UTL_SMTP, all text data (in other words, those in VARCHAR2) will be converted to US7ASCII before it is sent over the wire to the server. Some implementations of SMTP servers that support SMTP extension 8BITMIME [RFC1652] support full 8-bit communication between client and server.

The body of the DATA command may be transferred in full 8 bits, but the rest of the SMTP command and response should be in 7 bits. When the target SMTP server supports 8BITMIME extension, users of multibyte databases may convert their non-US7ASCII, multibyte VARCHAR2 data to RAW and use the write_raw_data() API to send multibyte data using 8-bit MIME encoding.

Also, note that UTL_SMTP provides API for SMTP communication as specified in RFC821. The package does not provide API to format the content of the message according to RFC 822 (for example, setting the subject of an electronic mail). It is the user's responsibility to format the message appropriately.

This chapter discusses the following topics:

• Example

• Exceptions, Limitations, and Reply Codes

• Summary of UTL_SMTP Subprograms

  Note : RFC documents are "Request for Comments" documents that describe proposed standards for public review on the Internet. For the actual RFC documents, please refer to: http://www.ietf.org/rfc/

Example

The following example illustrates how UTL_SMTP is used by an application to send e-mail. The application connects to an SMTP server at port 25 and sends a simple text message.

UTL_SMTP.send_mail (

sender      IN VARCHAR2, 
recipient   IN VARCHAR2, 
message     IN VARCHAR2)

IS
    mailhost    VARCHAR2(30) := 'mailhost.mydomain.com';
    mail_conn   utl_smtp.connection;
BEGIN
    mail_conn := utl_smtp.open_connection(mailhost, 25);
    utl_smtp.helo(mail_conn, mailhost);
    utl_smtp.mail(mail_conn, sender);
    utl_smtp.rcpt(mail_conn, recipient);
    utl_smtp.data(mail_conn, message);
    utl_smtp.quit(mail_conn);
EXCEPTION
    WHEN OTHERS THEN
        -- Handle the error
END;

Exceptions, Limitations, and Reply Codes

Exceptions

Table 82-1 lists the exceptions that can be raised by the API of the UTL_SMTP package. The network error is transferred to a reply code of 421- service not available.

Table 82-1 UTL_SMTP Exceptions

Exception	Description
INVALID_OPERATION	Raised when an invalid operation is made. In other words, calling API other than write_data(), write_raw_data() or close_data() after open_data() is called, or calling write_data(), write_raw_data() or close_data() without first calling open_data().
TRANSIENT_ERROR	Raised when receiving a reply code in 400 range.
PERMANENT_ERROR	Raised when receiving a reply code in 500 range.

Limitations

No limitation or range-checking is imposed by the API. However, you should be aware of the following size limitations on various elements of SMTP. Sending data that exceed these limits may result in errors returned by the server.

Table 82-2 SMTP Size Limitation

Element	Size Limitation
user	The maximum total length of a user name is 64 characters.
domain	The maximum total length of a domain name or number is 64 characters.
path	The maximum total length of a reverse-path or forward-path is 256 characters (including the punctuation and element separators).
command line	The maximum total length of a command line including the command word and the <CRLF> is 512 characters.
reply line	The maximum total length of a reply line including the reply code and the <CRLF> is 512 characters.
text line	The maximum total length of a text line including the <CRLF> is 1000 characters (but not counting the leading dot duplicated for transparency).
recipients buffer	The maximum total number of recipients that must be buffered is 100 recipients.

Reply Codes

The following is a list of the SMTP reply codes.

Table 82-3 SMTP Reply Codes

Reply Code	Meaning
211	System status, or system help reply
214	Help message [Information on how to use the receiver or the meaning of a particular non-standard command; this reply is useful only to the human user]
220	<domain> Service ready
221	<domain> Service closing transmission channel
250	Requested mail action okay, completed
251	User not local; will forward to <forward-path>
252	OK, pending messages for node <node> started. Cannot VRFY user (e.g., info is not local), but will take message for this user and attempt delivery.
253	OK, <messages> pending messages for node <node> started
354	Start mail input; end with <CRLF>.<CRLF>
355	Octet-offset is the transaction offset
421	<domain> Service not available, closing transmission channel (This may be a reply to any command if the service knows it must shut down.)
450	Requested mail action not taken: mailbox unavailable [for example, mailbox busy]
451	Requested action aborted: local error in processing
452	Requested action not taken: insufficient system storage
453	You have no mail.
454	TLS not available due to temporary reason. Encryption required for requested authentication mechanism.
458	Unable to queue messages for node <node>
459	Node <node> not allowed: reason
500	Syntax error, command unrecognized (This may include errors such as command line too long.)
501	Syntax error in parameters or arguments
502	Command not implemented
503	Bad sequence of commands
504	Command parameter not implemented
521	<Machine> does not accept mail.
530	Must issue a STARTTLS command first. Encryption required for requested authentication mechanism.
534	Authentication mechanism is too weak.
538	Encryption required for requested authentication mechanism.
550	Requested action not taken: mailbox unavailable [for example, mailbox not found, no access]
551	User not local; please try <forward-path>
552	Requested mail action aborted: exceeded storage allocation
553	Requested action not taken: mailbox name not allowed [for example, mailbox syntax incorrect]
554	Transaction failed

Summary of UTL_SMTP Subprograms

Table 82-4 UTL_SMTP Subprograms  

Subprogram	Description
"connection Record Type"	This is a PL/SQL record type used to represent a SMTP connection.
"reply, replies Record Types"	PL/SQL record types used to represent an SMTP reply line.
"open_connection Function"	Opens a connection to an SMTP server.
"command(), command_replies() Functions"	Performs a generic SMTP command.
"helo Function"	Performs initial handshaking with SMTP server after connecting.
"ehlo Function"	Performs initial handshaking with SMTP server after connecting, with extended information returned.
"mail Function"	Initiates a mail transaction with the server. The destination is a mailbox.
"rcpt Function"	Specifies the recipient of an e-mail message.
"data Function"	Specifies the body of an e-mail message.
"open_data(), write_data(), write_raw_data(), close_data() Functions"	Provide more fine-grain control to the data() API.
"rset Function"	Aborts the current mail transaction.
"vrfy Function"	Verifies the validity of a destination e-mail address.
"noop() Function"	The null command.
"quit Function"	Terminates an SMTP session and disconnects from the server.