xp_readmail

Description

(Windows only) Reads a message from the Adaptive Server message inbox.

Syntax

xp_readmail [msg_id]
	[, recipients  output]
	[, sender  output]
	[, date_received  output]
	[, subject  output]
	[, cc  output]
	[, message  output]
	[, attachments  output]
	[, suppress_attach = {true | false}]
	[, peek = {true | false}]
	[, unread = {true | false}]
	[, msg_length  output]
	[, bytes_to_skip  [output]]
	[, type [output]]

Parameters

msg _id

specifies the message identifier of the message to be read by xp_readmail. If the msg_id parameter is not used, the message defaults to the first unread message in the message box, if unread is true, or to the first message in the message box, if unread is false.

recipients

is a semicolon-separated list of the recipients of the message.

sender

is the originator of the message.

date_received

is the date the message was received.

subject

is the subject header of the message.

cc

is a list of the message’s copied (cc’d) recipients (separated by semicolons).

message

is the text of the message body. If the length of the message body, obtained from the msg_length output parameter, is greater than 255, use the byte_to_skip and msg_length parameters to read the message in 255-byte increments.

attachments

is a list of the temporary paths of the attachments (separated by semicolons). attachments is ignored if suppress_attach is true.

suppress_attach

if set to true, prevents the creation of temporary files for attachments. The default is true.

peek

if set to false, flags the message as unread after it has been read. If set to true, flags the message as an unread message, even after it has been read. The default is false.

unread_only

if set to true, xp_readmail considers only unread messages. If set to false, xp_readmail considers all messages, whether they are flagged as read or unread. The default is true.

msg_length

is the total length of the message, in bytes. Used with the bytes_to_skip parameter, allows xp_readmail to read messages in 255-byte increments.

bytes_to_skip

on input, if not 0, specifies the number of bytes to skip before reading the next 255 bytes of the message into the message output parameter. On output, contains the offset in the message (the previous value of bytes_to_skip plus the msg_length that is output with the call) from which to start reading the next 255-byte increment.

type

is the message type based on the MAPI mail definition. The only supported message type is CMC:IPM. A NULL value or no value defaults to CMC:IPM.

Examples

Example 1

xp_readmail reads the first unread message in the message inbox. It gets the message identifier for this message from the @msgid variable, where it has been stored by the xp_findnextmsg ESP. xp_readmail stores the sender’s name in the @originator variable and the message body in the @mess variable:

declare @msgid binary(255)
declare @originator varchar(20)
declare @mess varchar(255)
exec xp_findnextmsg @msg_id = @msgid output
exec xp_readmail @msg_id = @msgid,
@sender = @originator output,
@message = @mess output

Example 2

Reads the first 255 bytes of the message for which the message identifier is output by xp_findnextmsg. If the total length of the message exceeds 255 bytes, reads the next 255 bytes and continues until there are no more bytes to read:

declare @msgid binary(255)
declare @mess varchar(255)
declare @msg_length char(255)
declare @len int
declare @skip int
exec xp_findnextmsg @msgid output
exec xp_readmail @msg_id = @msgid,
@message = @mess output,
@msg_length = @len output,
@bytes_to_skip = @skip output
print @mess
if (@len > 255)
begin
        while (@skip < @len)
        begin
            xp_readmail @msg_id = @msgid,
            @message = @mess output,
            @bytes_to_skip = @skip output
            print @mess
        end
end

Usage

Permissions

By default, only a System Administrator can execute xp_readmail. A System Administrator can grant this permission to other users.