UTL_SMTP , 2 of 3

Summary of UTL_SMTP Subprograms

Table 100-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.

connection Record Type

This is a PL/SQL record type used to represent an SMTP connection.

Syntax

TYPE connection IS RECORD (
    host              VARCHAR2(255),      -- remote host name
    port              PLS_INTEGER,        -- remote port number
    tx_timeout        PLS_INTEGER,        -- Transfer time-out (in seconds) 
    private_tcp_con   utl_tcp.connection, -- private, for implementation use
    private_state     PLS_INTEGER         -- private, for implementation use
);

Fields

Table 100-5 connection Record Type Fields

Field	Description
`host`	The name of the remote host when connection is established. `NULL` when no connection is established.
`port`	The port number of the remote SMTP server connected. `NULL` when no connection is established.
`tx_timeout`	The time in seconds that the `UTL_SMTP` package waits before giving up in a read or write operation in this connection. In read operations, this package gives up if no data is available for reading immediately. In write operations, this package gives up if the output buffer is full and no data is to be sent into the network without being blocked. `0` indicates not to wait at all. `NULL` indicates to wait forever.
`private_tcp_con`	Private, for implementation use only. You should not modify this field.
`private_state`	Private, for implementation use only. You should not modify this field.

Usage Notes

The read-only fields in a connection record are used to return information about the SMTP connection after the connection is successfully made with open_connection(). Changing the values of these fields has no effect on the connection. The fields private_xxx are for implementation use only. You should not modify these fields.

reply, replies Record Types

These are PL/SQL record types used to represent an SMTP reply line. Each SMTP reply line consists of a reply code followed by a text message. While a single reply line is expected for most SMTP commands, some SMTP commands expect multiple reply lines. For those situations, a PL/SQL table of reply records is used to represent multiple reply lines.

Syntax

TYPE reply IS RECORD (
  code    PLS_INTEGER,       -- 3-digit reply code
  text    VARCHAR2(508)      -- text message
);
TYPE replies IS TABLE OF reply INDEX BY BINARY_INTEGER;   -- multiple reply 
lines

Fields

Table 100-6 reply, replies Record Type Fields

Field	Description
`code`	The 3-digit reply code.
`text`	The text message of the reply.

open_connection Function

This function opens a connection to an SMTP server.

Syntax

UTL_SMTP.OPEN_CONNECTION (
   host        IN  VARCHAR2, 
   port        IN  PLS_INTEGER DEFAULT 25, 
   c           OUT connection, 
   tx_timeout  IN  PLS_INTEGER DEFAULT NULL) 
RETURN reply; 
UTL_SMTP.OPEN_+CONNECTION (
   host        IN  VARCHAR2, 
   port        IN  PLS_INTEGER DEFAULT 25, 
   tx_timeout  IN  PLS_INTEGER DEFAULT NULL) 
RETURN connection;

Parameters

Table 100-7 open_connection Function Parameters

Parameter	Description
`host (IN)`	The name of the SMTP server host
`port (IN)`	The port number on which SMTP server is listening (usually 25).
`tx_timeout (IN)`	The time in seconds that the `UTL_SMTP` package waits before giving up in a read or write operation in this connection. In read operations, this package gives up if no data is available for reading immediately. In write operations, this package gives up if the output buffer is full and no data is to be sent into the network without being blocked. `0` indicates not to wait at all. `NULL` indicates to wait forever.

Usage Notes

The expected response from the server is a message beginning with status code 220.

The version of open_connection()API that returns utl_smtp.connection record is actually the procedure version of open_connection that checks the reply code returned by an SMTP server when the connection is first established.

A timeout on the write operations feature is not supported in the current release of this package.

command(), command_replies() Functions

These functions perform generic SMTP commands.

Syntax

UTL_SMTP.COMMAND (
   c    IN connection,
   cmd  IN VARCHAR2,
   arg  IN VARCHAR2 DEFAULT NULL) 
RETURN reply;
UTL_SMTP.COMMAND (
   c    IN connection,
   cmd  IN VARCHAR2,
   arg  IN ARCHAR2 DEFAULT NULL);
UTL_SMTP.COMMAND_REPLIES (
   c    IN connection,
   cmd  IN VARCHAR2,
   arg  IN VARCHAR2 DEFAULT NULL)
RETURN replies;

Parameters

Table 100-8 command (), command_replies () Function Parameters

Parameter	Description
`c (IN)`	The SMTP connection.
`cmd (IN)`	The SMTP command to send to the server.
`arg (IN)`	The optional argument to the SMTP argument. A space will be inserted between `cmd` and `arg`.

Usage Notes

These are the APIs used to invoke generic SMTP commands. Use command() if only a single reply line is expected. Use command_replies() if multiple reply lines are expected (in other words, EXPN or HELP).

For command(), if multiple reply lines are returned from the SMTP server, it returns the last reply line only.

helo Function

This function performs initial handshaking with SMTP server after connecting.

Syntax

UTL_SMTP.HELO (
   c  IN NOCOPY connection, domain IN NOCOPY) 
RETURN reply;
UTL_SMTP.HELO (
   c  IN NOCOPY connection, domain IN NOCOPY);

Parameters

Table 100-9 helo Function Parameters

Parameter	Description
`c (IN NOCOPY)`	The SMTP connection.
`domain (IN NOCOPY)`	The domain name of the local (sending) host. Used for identification purposes.

Usage Notes

RFC 821 specifies that the client must identify itself to the server after connecting. This routine performs that identification. The connection must have been opened via a call to open_connection() before calling this routine.

The expected response from the server is a message beginning with status code 250.

Related Functions

ehlo()

ehlo Function

This function performs initial handshaking with SMTP server after connecting, with extended information returned.

Syntax

UTL_SMTP.EHLO (
   c       IN OUT NOCOPY connection, 
   domain  IN NOCOPY) 
RETURN replies;
UTL_SMTP.EHLO (
   c       IN OUT NOCOPY connection, 
   domain  IN NOCOPY);

Parameters

Table 100-10 ehlo Function Parameters

Parameter	Description
`c (IN NOCOPY)`	The SMTP connection.
`domain (IN NOCOPY)`	The domain name of the local (sending) host. Used for identification purposes.

Usage Notes

The ehlo() interface is identical to helo(), except that it allows the server to return more descriptive information about its configuration. [RFC1869] specifies the format of the information returned, which the PL/SQL application can retrieve using the functional form of this call. For compatibility with helo(), each line of text returned by the server begins with status code 250.

Related Functions

helo()

mail Function

This function initiates a mail transaction with the server. The destination is a mailbox.

Syntax

UTL_SMTP.MAIL (
   c           IN OUT NOCOPY connection, 
   sender      IN OUT NOCOPY, 
   parameters  IN OUT NOCOPY) 
RETURN reply;
UTL_SMTP.MAIL (
   c           IN OUT NOCOPY connection,
   sender      IN OUT NOCOPY, 
   parameters  IN OUT NOCOPY);

Parameters

Table 100-11 Mail Function Parameters

Parameter	Description
`c (IN NOCOPY)`	The SMTP connection.
`sender (IN OUT NOCOPY)`	The e-mail address of the user sending the message.
`parameters (IN OUT NOCOPY)`	The additional parameters to MAIL command as defined in Section 6 of [RFC1869]. It should follow the format of "XXX=XXX (XXX=XXX ....)".

Usage Notes

This command does not send the message; it simply begins its preparation. It must be followed by calls to rcpt() and data() to complete the transaction. The connection to the SMTP server must be open and a helo() or ehlo() command must have already been sent.

The expected response from the server is a message beginning with status code 250.

rcpt Function

This function specifies the recipient of an e-mail message.

Syntax

UTL_SMTP.RCPT (
   c           IN OUT NOCOPY connection, 
   recipient   IN OUT NOCOPY,
   parameters  IN OUT NOCOPY) 
RETURN reply;
UTL_SMTP.RCPT (
   c           IN OUT NOCOPY connection
   recipient   IN OUT NOCOPY,
   parameters  IN OUT NOCOPY);

Table 100-12 rcpt Function Parameters

Parameter	Description
`c (IN OUT NOCOPY)`	The SMTP connection.
`recipient (IN OUT NOCOPY)`	The e-mail address of the user to which the message is being sent.
`parameters (IN OUT NOCOPY)`	The additional parameters to RCPT command as defined in Section 6 of [RFC1869]. It should follow the format of "XXX=XXX (XXX=XXX ....)".

Usage Notes

To send a message to multiple recipients, call this routine multiple times. Each invocation schedules delivery to a single e-mail address. The message transaction must have been begun by a prior call to mail(), and the connection to the mail server must have been opened and initialized by prior calls to open_connection() and helo() or ehlo(), respectively.

The expected response from the server is a message beginning with status code 250 or 251.

data Function

This function specifies the body of an e-mail message.

Syntax

UTL_SMTP.DATA (
   c     IN OUT NOCOPY connection
   body  IN OUT NOCOPY) 
RETURN reply;
UTL_SMTP.DATA (
   c     IN OUT NOCOPY connection
   body  IN OUT NOCOPY);

Parameters

Table 100-13 data Function Parameters

Parameter	Description
`c (IN OUT NOCOPY)`	The SMTP Connection.
`body (IN OUT NOCOPY)`	The text of the message to be sent, including headers, in [RFC822] format.

Usage Notes

The application must ensure that the contents of the body parameter conform to the MIME(RFC822) specification. The data() routine will terminate the message with a <CR><LF>.<CR><LF> sequence (a single period at the beginning of a line), as required by RFC821. It will also translate any sequence of <CR><LF>.<CR><LF> (single period) in body to <CR><LF>..<CR><LF> (double period). This conversion provides the transparency as described in Section 4.5.2 of RFC821.

The data() call should be called only after open_connection(), helo() / ehlo(), mail() and rcpt() have been called. The connection to the SMTP server must be open, and a mail transaction must be active when this routine is called.

The expected response from the server is a message beginning with status code 250. The 354 response received from the initial DATA command will not be returned to the caller.

open_data(), write_data(), write_raw_data(), close_data() Functions

These APIs provide more fine-grain control to the data() API; in other words, to the SMTP DATA operation. open_data() sends the DATA command. After that, write_data() and write_raw_data() write a portion of the e-mail message. A repeat call to write_data() and write_raw_data() appends data to the e-mail message. The close_data() call ends the e-mail message by sending the sequence <CR><LF>.<CR><LF> (a single period at the beginning of a line).

Syntax

UTL_SMTP.OPEN_DATA (
   c     IN OUT NOCOPY connection) 
RETURN reply;
UTL_SMTP.OPEN_DATA (
   c     IN OUT NOCOPY connection);
UTL_SMTP.WRITE_DATA (
   c     IN OUT NOCOPY connection, 
   data  IN OUT NOCOPY);
UTL_SMTP.WRITE_RAW_DATA (
   c     IN OUT NOCOPY connection
   data  IN OUT NOCOPY);
UTL_SMTP.CLOSE_DATA (
   c     IN OUT NOCOPY connection) 
RETURN reply;
UTL_SMTP.CLOSE_DATA (
   c     IN OUT NOCOPY connection);

Parameters

Table 100-14 open_data(), write_data(), write_raw_data(), close_data() Function Parameters

Parameter	Description
`c (IN OUT NOCOPY)`	The SMTP connection.
`data (IN OUT NOCOPY)`	The portion of the text of the message to be sent, including headers, in [RFC822] format.

Usage Notes

The calls to open_data(), write_data(), write_raw_data() and close_data() must be made in the right order. A program calls open_data() to send the DATA command to the SMTP server. After that, it can call write_data() or write_raw_data() repeatedly to send the actual data. The data is terminated by calling close_data(). After open_data() is called, the only APIs that can be called are write_data(), write_raw_data(), or close_data(). A call to other APIs will result in an INVALID_OPERATION exception being raised.

The application must ensure that the contents of the body parameter conform to the MIME(RFC822) specification. The data() routine will terminate the message with a <CR><LF>.<CR><LF> sequence (a single period at the beginning of a line), as required by RFC821. It will also translate any sequence of <CR><LF>.<CR><LF> (single period) in the body to <CR><LF>..<CR><LF> (double period). This conversion provides the transparency as described in Section 4.5.2 of RFC821.

Notice that this conversion is not bullet-proof. Consider this code fragment:

  utl_smtp.write_data(`some message.' || chr(13) || chr(10));
  utl_smtp.write_data(`.' || chr(13) || chr(10));

Since the sequence <CR><LF>.<CR><LF> is split between two calls to write_data(), the implementation of write_data() will not detect the presence of the data-terminator sequence, and therefore, will not perform the translation. It will be the responsibility of the user to handle such a situation, or it may result in premature termination of the message data.

XXX_data() should be called only after open_connection(), helo()/ ehlo(), mail(), and rcpt() have been called. The connection to the SMTP server must be open and a mail transaction must be active when this routine is called.

Note that there is no function form of write_data() because the SMTP server does not respond until the data-terminator is sent during the call to close_data().

Text (VARCHAR2) data sent using write_data() API is converted to US7ASCII before it is sent. If the text contains multibyte characters, each multibyte character in the text that cannot be converted to US7ASCII is replaced by a `?' character. If 8BITMIME extension is negotiated with the SMTP server using the EHLO() API, multibyte VARCHAR2 data can be sent by first converting the text to RAW using the UTL_RAW package, and then sending the RAW data using write_raw_data().

rset Function

This function aborts the current mail transaction.

Syntax

UTL_SMTP.RSET (
   c  IN OUT NOCOPY connection) 
RETURN reply;
UTL_SMTP.RSET (
   c  IN OUT NOCOPY connection);

Parameters

Table 100-15 rset Function Parameters

Parameter	Description
`c (IN OUT NOCOPY)`	The SMTP connection.

Usage Notes

This command allows the client to abandon a mail message it was in the process of composing. No mail will be sent. The client can call rset() at any time after the connection to the SMTP server has been opened via open_connection(). The server will always respond to RSET with a message beginning with status code 250.

Related Functions

quit()

vrfy Function

This function verifies the validity of a destination e-mail address.

Syntax

UTL_SMTP.VRFY (
   c          IN OUT NOCOPY connection
   recipient  IN OUT NOCOPY) 
RETURN reply;

Parameters

Table 100-16 vrfy Function Parameters

Parameter	Description
`c (IN OUT NOCOPY)`	The SMTP connection.
`recipient (IN OUT NOCOPY)`	The e-mail address to be verified.

Usage Notes

The server attempts to resolve the destination address recipient. If successful, it returns the recipient's full name and fully qualified mailbox path. The connection to the server must have already been established via open_connection() and helo() / ehlo() before making this request.

Successful verification returns one or more lines beginning with status code 250 or 251.

Related Functions

expn()

noop() Function

The null command.

Syntax

UTL_SMTP.NOOP (
   c  IN OUT NOCOPY connection) 
RETURN VARCHAR2;
UTL_SMTP.NOOP (
   c  IN OUT NOCOPY connection);

Parameter

Table 100-17 noop Function Parameters

Parameter	Description
`c (IN OUT NOCOPY)`	The SMTP connection.

Usage Notes

This command has no effect except to elicit a successful reply from the server. It can be issued at any time after the connection to the server has been established with open_connection(). The noop() command can be used to verify that the server is still connected and is listening properly.

This command will always reply with a single line beginning with status code 250.

quit Function

This function terminates an SMTP session and disconnects from the server.

Syntax

UTL_SMTP.QUIT (
   c  IN OUT NOCOPY connection) 
RETURN VARCHAR2;

Parameter

Table 100-18 quit Function Parameters

Parameter	Description
`c (IN OUT NOCOPY)`	The SMTP connection.

Usage Notes

The quit() command informs the SMTP server of the client's intent to terminate the session. It then closes the connection established by open_connection(), which must have been called before executing this command. If a mail transaction is in progress when quit() is issued, it is abandoned in the same manner as rset().

The function form of this command returns a single line beginning with the status code 221 on successful termination. In all cases, the connection to the SMTP server is closed. The fields remote_host and remote_port of c are reset.

Related Functions

rset()