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

xp_readmail reads a message from the Adaptive Server message inbox.

To get the message identifier of the next message in the message inbox, use xp_findnextmsg.

Permissions

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