xp_findnextmsg (Transact-SQL)

[ @type=] type

Is the input message type based on the MAPI definition:

IP[M|C].Vendorname.subclass

If type is NULL, message types that start with IPM appear in the inbox of the mail client and are found or read by xp_findnextmsg. Message types that start with IPC do not appear in the inbox of the mail client and must be found or read by setting the type parameter. The default is NULL. SQL Mail supports message types of IPM and IPC.

[ @unread_only=] 'unread_value'

Is whether only unread (N'TRUE') messages are considered. The default is N'FALSE', which means all messages are considered. unread_value is of type nvarchar(5).

[ @msg_id=] 'message_id'

Is an input and output parameter that specifies the string of the message on input and the string of the next message on output. If message_id for the input is NULL, then by default, the output @msg_id will be the ID for the most recently delivered message in the Inbox. message_id is varchar(255), with a default of NULL.

OUTPUT

When specified, message_id is placed in the output parameter. When not specified, message_id is returned as a single-column, single-row result set.

0 (success) or 1 (failure)

xp_findnextmsg returns a message when passed a valid message ID.

When @msg_id is NULL, xp_findnextmsg returns the following result set.

Any failure except an invalid parameter is logged to the Microsoft Windows application log.

Requires membership in the sysadmin fixed server role, but EXECUTE permissions can be granted to other users. However, for security reasons, we recommend that permissions for this stored procedure be limited to members of the sysadmin fixed server role.

The following example retrieves the status when searching for the next message ID (for only unread messages). The value from xp_findnextmsg is placed in the local variable @message_id.

DECLARE @status int, @message_id varchar(255) ;

EXEC @status = xp_findnextmsg @msg_id = @message_id OUTPUT ;

Reference