| PL/SQL Packages and Types Reference 10g Release 1 (10.1) Part Number B10802-01 |
|
|
View PDF |
| PL/SQL Packages and Types Reference 10g Release 1 (10.1) Part Number B10802-01 |
|
|
View PDF |
The UTL_SMTP package is designed for sending electronic mails (emails) over Simple Mail Transfer Protocol (SMTP) as specified by RFC821.
| See Also:
How to use the SMTP package to send email in Oracle Database Application Developer's Guide - Fundamentals |
This chapter contains the following topics:
The protocol consists of a set of commands for an email client to dispatch emails to a SMTP server. The UTL_SMTP package provides interfaces to the SMTP commands. For many of the commands, the package provides both a procedural and a functional interface. The functional form returns the reply from the server for processing by the client. The procedural form checks the reply and will raise an exception if the reply indicates a transient (400-range reply code) or permanent error (500-range reply code). Otherwise, it discards the reply.
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 subprogram to send multibyte data using 8-bit MIME encoding.
UTL_SMTP provides for SMTP communication as specified in RFC821, but does not provide an API to format the content of the message according to RFC 822 (for example, setting the subject of an electronic mail).You must format the message appropriately. In addition, UTL_SMTP does not have the functionality to implement an SMTP server for an email clients to send emails using SMTP.
|
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: |
This is a PL/SQL record type used to represent an SMTP connection.
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 );
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.
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.
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
| Field | Description |
|---|---|
|
|
The 3-digit reply code. |
|
|
The text message of the reply. |
The following is a list of the SMTP reply codes.
The table lists the exceptions that can be raised by the interface of the UTL_SMTP package. The network error is transferred to a reply code of 421- service not available.
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.
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.
DECLARE c UTL_SMTP.CONNECTION; PROCEDURE send_header(name IN VARCHAR2, header IN VARCHAR2) AS BEGIN UTL_SMTP.WRITE_DATA(c, name || ': ' || header || UTL_TCP.CRLF); END; BEGIN c := UTL_SMTP.OPEN_CONNECTION('smtp-server.acme.com'); UTL_SMTP.HELO(c, 'foo.com'); UTL_SMTP.MAIL(c, 'sender@foo.com'); UTL_SMTP.RCPT(c, 'recipient@foo.com'); UTL_SMTP.OPEN_DATA(c); send_header('From', '"Sender" <sender@foo.com>'); send_header('To', '"Recipient" <recipient@foo.com>'); send_header('Subject', 'Hello'); UTL_SMTP.WRITE_DATA(c, UTL_TCP.CRLF || 'Hello, world!'); UTL_SMTP.CLOSE_DATA(c); UTL_SMTP.QUIT(c); EXCEPTION WHEN utl_smtp.transient_error OR utl_smtp.permanent_error THEN BEGIN UTL_SMTP.QUIT(c); EXCEPTION WHEN UTL_SMTP.TRANSIENT_ERROR OR UTL_SMTP.PERMANENT_ERROR THEN NULL; -- When the SMTP server is down or unavailable, we don't have -- a connection to the server. The QUIT call will raise an -- exception that we can ignore. END; raise_application_error(-20000, 'Failed to send mail due to the following error: ' || sqlerrm); END;
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).
UTL_SMTP.CLOSE_DATA ( c IN OUT NOCOPY connection) RETURN reply; UTL_SMTP.CLOSE_DATA ( c IN OUT NOCOPY connection);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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 subprograms 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.
CLOSE_DATA should be called only after OPEN_CONNECTION, HELO or 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.
This function/procedure performs a generic SMTP command.
UTL_SMTP.COMMAND ( c IN OUT NOCOPY connection, cmd IN VARCHAR2, arg IN VARCHAR2 DEFAULT NULL) RETURN reply; UTL_SMTP.COMMAND ( c IN OUT NOCOPY connection, cmd IN VARCHAR2, arg IN VARCHAR2 DEFAULT NULL);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The SMTP command to send to the server. |
|
|
The optional argument to the SMTP argument. A space will be inserted between |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
This function is 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.
For COMMAND, if multiple reply lines are returned from the SMTP server, it returns the last reply line only.
This functions performs a generic SMTP command.
UTL_SMTP.COMMAND_REPLIES ( c IN OUT NOCOPY connection, cmd IN VARCHAR2, arg IN VARCHAR2 DEFAULT NULL) RETURN replies;
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The SMTP command to send to the server. |
|
|
The optional argument to the SMTP argument. A space will be inserted between |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). |
This function is 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.
For COMMAND, if multiple reply lines are returned from the SMTP server, it returns the last reply line only.
This function/procedure specifies the body of an e-mail message.
UTL_SMTP.DATA ( c IN OUT NOCOPY connection body IN VARCHAR2 CHARACTER SET ANY_CS) RETURN reply; UTL_SMTP.DATA ( c IN OUT NOCOPY connection body IN VARCHAR2 CHARACTER SET ANY_CS);
| Parameter | Description |
|---|---|
|
|
The SMTP Connection. |
|
|
The text of the message to be sent, including headers, in [RFC822] format. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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 or 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.
This function/procedure performs initial handshaking with SMTP server after connecting, with extended information returned.
UTL_SMTP.EHLO ( c IN OUT NOCOPY connection, domain IN) RETURN replies; UTL_SMTP.EHLO ( c IN OUT NOCOPY connection, domain IN);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The domain name of the local (sending) host. Used for identification purposes. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). |
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.
HELO
This function/procedure performs initial handshaking with SMTP server after connecting.
UTL_SMTP.HELO ( c IN OUT NOCOPY connection, domain IN VARCHAR2) RETURN reply; UTL_SMTP.HELO ( c IN OUT NOCOPY connection, domain IN VARCHAR2);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The domain name of the local (sending) host. Used for identification purposes. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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 through a call to OPEN_CONNECTION Functions before calling this routine.
The expected response from the server is a message beginning with status code 250.
EHLO
This function sends the HELP command.
UTL_SMTP.HELP ( c IN OUT NOCOPY connection, command IN VARCHAR2 DEFAULT NULL) RETURN replies;
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The command to get the help message. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). |
This function/procedure initiates a mail transaction with the server. The destination is a mailbox.
UTL_SMTP.MAIL ( c IN OUT NOCOPY connection, sender IN VARCHAR2, parameters IN VARCHAR2 DEFAULT NULL) RETURN reply; UTL_SMTP.MAIL ( c IN OUT NOCOPY connection, sender IN VARCHAR2, parameters IN VARCHAR2 DEFAULT NULL);
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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.
The null command.
UTL_SMTP.NOOP ( c IN OUT NOCOPY connection) RETURN reply; UTL_SMTP.NOOP ( c IN OUT NOCOPY connection);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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.
These functions open a connection to an SMTP server.
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;
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
OPEN_CONNECTION that returns UTL_SMTP.CONNECTION record checks the reply code returned by an SMTP server when the connection is first established. It raises an exception when the reply indicates an error. Otherwise, it discards the reply. If a user is interested in examining the reply, he or she can invoke the version of OPEN_CONNECTION that returns REPLY.WRITE operations feature is not supported in the current release of this package.OPEN_DATA sends the DATA command after which you can use WRITE_DATA and WRITE_RAW_DATA to write a portion of the e-mail message.
UTL_SMTP.OPEN_DATA ( c IN OUT NOCOPY connection) RETURN reply; UTL_SMTP.OPEN_DATA ( c IN OUT NOCOPY connection);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The portion of the text of the message to be sent, including headers, in [RFC822] format. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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 subprograms 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.
OPEN_DATA should be called only after OPEN_CONNECTION, HELO or 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.
This function terminates an SMTP session and disconnects from the server.
UTL_SMTP.QUIT ( c IN OUT NOCOPY connection) RETURN reply; UTL_SMTP.QUIT ( c IN OUT NOCOPY connection);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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.
RSET
This function/procedure specifies the recipient of an e-mail message.
UTL_SMTP.RCPT ( c IN OUT NOCOPY connection, recipient IN VARCHAR2, parameters IN VARCHAR2 DEFAULT NULL) RETURN reply; UTL_SMTP.RCPT ( c IN OUT NOCOPY connection, recipient IN VARCHAR2, parameters IN VARCHAR2 DEFAULT NULL);
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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.
This function terminates the current mail transaction.
UTL_SMTP.RSET ( c IN OUT NOCOPY connection) RETURN reply; UTL_SMTP.RSET ( c IN OUT NOCOPY connection);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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 by means of OPEN_CONNECTION until DATA or OPEN_DATA is called. Once the email data has been sent, it will be too late to prevent the email from being sent.
The server will always respond to RSET with a message beginning with status code 250.
QUIT
This function verifies the validity of a destination e-mail address.
UTL_SMTP.VRFY ( c IN OUT NOCOPY connection recipient IN VARCHAR2) RETURN reply;
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The e-mail address to be verified. |
| Return Value | Description |
|---|---|
|
|
Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned. |
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 by means of OPEN_CONNECTION and HELO or EHLO before making this request.
Successful verification returns one or more lines beginning with status code 250 or 251.
Use WRITE_DATA to write a portion of the e-mail message. A repeat call to WRITE_DATA appends data to the e-mail message.
UTL_SMTP.WRITE_DATA ( c IN OUT NOCOPY connection, data IN VARCHAR2 CHARACTER SET ANY_CS);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The portion of the text of the message to be sent, including headers, in [RFC822] format. |
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 subprograms 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.
WRITE_DATA should be called only after OPEN_CONNECTION, HELO or 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 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 subprogram, 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.
Use WRITE_RAW_DATA to write a portion of the e-mail message. A repeat call to WRITE_RAW_DATA appends data to the e-mail message.
UTL_SMTP.WRITE_RAW_DATA ( c IN OUT NOCOPY connection data IN RAW);
| Parameter | Description |
|---|---|
|
|
The SMTP connection. |
|
|
The portion of the text of the message to be sent, including headers, in [RFC822] format. |
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 subprograms 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 or 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 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 subprogram, 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.
|
 Copyright © 1998, 2003 Oracle Corporation All Rights Reserved. |
|