xp_readmail (Transact-SQL)

Lê um email da caixa de entrada do SQL Mail. Este procedimento é usado por sp_processmail para processar todo o correio na caixa de entrada do SQL Mail.

Observação
Esse recurso será removido em uma versão futura do Microsoft SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.

Convenções de sintaxe Transact-SQL

Sintaxe

xp_readmail [ [ @msg_id= ] 'message_id' ]
     [ , [ @type= ] 'type' [ OUTPUT ] ] 
     [ , [ @peek= ] 'peek' ]
     [ , [ @suppress_attach= ] 'suppress_attach' ]
     [ , [ @originator= ] 'sender' OUTPUT ]
     [ , [ @subject= ] 'subject' OUTPUT ]
     [ , [ @message= ] 'message' OUTPUT ]
     [ , [ @recipients= ] 'recipients [ ;...n ]' OUTPUT ]
     [ , [ @cc_list= ] 'copy_recipients [ ;...n ]' OUTPUT ]
     [ , [ @bcc_list= ] 'blind_copy_recipients [ ;...n ]' OUTPUT ]
     [ , [ @date_received= ] 'date' OUTPUT ]
     [ , [ @unread= ] 'unread_value' OUTPUT ]
     [ , [ @attachments= ] 'attachments [ ;...n ]' OUTPUT ])
     [ , [ @skip_bytes= ] bytes_to_skip OUTPUT ]
     [ , [ @msg_length= ] length_in_bytes OUTPUT ]
     [ , [ @originator_address= ] 'sender_address' OUTPUT ] ]

Argumentos

• [ @msg_id = ] 'message_id'
  É o ID da mensagem a ser lida. message_id é varchar(255), sem padrão.

• [ @type = ] 'type'
  É o tipo de mensagem a ser retornada com base na definição de MAPI:

  IP[ M|C ].Vendorname.subclass

  Se for usado na saída, deverá definir o tipo de uma mensagem específica; type será ignorado na saída se message_id for NULL. type é varchar(255), com um padrão NULL. O SQL Mail oferece suporte aos tipos de mensagem IPM e IPC.

• OUTPUT
  Quando for especificado, coloca o valor do parâmetro especificado no parâmetro de saída.

• [ @peek = ] 'peek'
  É o fato de o SQL Server retornar o email sem alterar o status para lido. peek é varchar(5), com um padrão FALSE. Se for definido como FALSE, o correio será tratado como se tivesse sido lido. Se for definido como TRUE, o correio será tratado como se não tivesse sido lido.

• [ @suppress_attach = ] 'suppress_attach'
  É o fato de os anexos de correio serem suprimidos. suppress_attaché varchar(255), com um padrão FALSE. Se for definido como TRUE, o SQL Server impedirá a criação de arquivos temporários quando xp_readmail ler uma mensagem com anexos. Se for definido como FALSE, não há prevenção de arquivos temporários quando forem lidas mensagens com anexos.

• [ @originator = ] 'sender'
  É o remetente do correio retornado. senderé varchar(255), sem padrão.

• [ @subject = ] 'subject'
  É o assunto retornado do email. subject é varchar(255), sem padrão.

• [ @message = ] 'message'
  É o corpo retornado ou o texto real do email. message é text, sem padrão.

• [ @recipients = ] 'recipients [ ;... n] '
  É a lista separada por ponto-e-vírgula dos destinatários do email a ser retornado. Os nomes de destinatários são separados por um ponto-e-vírgula (;). recipient_list é varchar(255), sem padrão.

• [ @cc_list = ] 'copy_recipients [ ;... n] '
  É a lista separada por ponto-e-vírgula dos destinatários no campo Cc do email a ser retornado. Os nomes de destinatários são separados por um ponto-e-vírgula (;). cc_list é varchar(255), sem padrão.

• [ @bcc_list = ] 'blind_copy_recipients[ ;... n] '
  É a lista separada por ponto-e-vírgula dos destinatários no campo Cco do email a ser retornado. Os nomes de destinatários são separados por um ponto-e-vírgula (;). bcc_list é varchar(255), sem padrão. Se o servidor de email não fornecer um valor para o campo Cco, blind_copy_recipients estará vazio.

• [ @date_received = ] 'date'
  É a data de retorno do email. date é varchar(255), sem padrão.

• [ @unread = ] 'unread_value'
  É o fato de uma mensagem ter sido lida anteriormente (true) ou não (false). unread_value é varchar(5), com um padrão TRUE.

• [ @attachments = ] 'attachments [ ;... n] '
  É a lista separada por ponto-e-vírgula dos caminhos temporários retornados dos anexos de correio da mensagem. Os caminhos temporários são separados por um ponto-e-vírgula (;). attachments é varchar(255), sem padrão.

• [ @skip_bytes = ] bytes_to_skipOUTPUT
  Se um valor diferente de 0 for passado para a entrada, este parâmetro especificará o número de bytes a serem ignorados antes de ler os próximos 255 bytes (máx.) da mensagem no parâmetro de saída body_of_message. Quando bytes_to_skip for usado, body_of_message incluirá a próxima parte da mensagem e bytes_to_skip será retornado com o próximo ponto inicial da mensagem (o bytes_to_skip anterior mais o comprimento da message). bytes_to_skip é int, com um padrão 0.

• [ @msg_length = ] length_in_bytesOUTPUT
  É o comprimento total da mensagem, em bytes. Quando for usado com bytes_to_skip em um procedimento armazenado, este parâmetro permite que mensagens sejam lidas em blocos de 255 bytes. length_in_bytes é int.

• [ @originator_address = ] 'sender_address'
  É o endereço de correio resolvido do originador do email. sender_address é varchar(255), sem padrão.

Valores de código de retorno

0 (êxito) ou 1 (falha)

Conjuntos de resultados

xp_readmail retorna um conjunto de resultados com estas colunas.

Nome da coluna	Descrição
Originador	Remetente de mensagem de email
Data do recebimento	Data em que a mensagem de email foi recebida
Destinatários	As pessoas para quem a mensagem foi enviada
Lista Cc	As pessoas na linha "Cc:" da mensagem de email
Lista Cco	As pessoas na linha "Cco:" da mensagem de email
Assunto	A linha de assunto da mensagem de email.
Mensagem	Corpo da mensagem (texto)
Não lido	Se esta mensagem não foi lida
Anexos	Qualquer anexo da mensagem
ID da mensagem	ID da mensagem
Tipo	Tipo de mensagem

Comentários

Qualquer falha, com exceção de um parâmetro inválido, será registrada no log de aplicativos do Microsoft Windows.

Há dois modos de usar xp_readmail:

• Retornar todas as mensagens da caixa de entrada como um conjunto de resultados para o cliente.

• Ler uma única mensagem da caixa de entrada.

Para retornar o conteúdo da caixa de entrada como um conjunto de resultados para o cliente, não forneça nenhum parâmetro de entrada.

A falha em alterar o padrão do parâmetro suppress_attach para TRUE gera dois problemas potenciais de segurança para anexos.

• Primeiro, se dois usuários diferentes compartilharem o mesmo diretório temporário e efetuarem logon no mesmo computador, eles poderão exibir os anexos um do outro. É possível determinar onde os anexos são armazenados e se dois usuários compartilham o mesmo diretório temporário recuperando-se a variável de saída attachments.

• Segundo, xp_deletemail não exclui estes anexos, assim você deve excluir cada anexo manualmente.

Para ler uma única mensagem da caixa de entrada, forneça um message_id válido retornado por xp_findnextmsg como um parâmetro de entrada para xp_readmail. Você pode especificar peek e suppress_attach como parâmetros de entrada a fim de controlar o modo que a mensagem é lida. Ao usar peek e suppress_attach com este método, todos os demais parâmetros são parâmetros de saía opcionais que contêm informações específicas da mensagem a ser lida.

Você pode exibir um exemplo de uso de xp_findnextmsg como um parâmetro de entrada para xp_readmail executando o seguinte comando:

sp_helptext 'sp_processmail';

Quando for usado para ler uma única mensagem, xp_readmail pode ler texto de mensagem com mais de 255 bytes nas seções. Use length_in_bytes para ler texto de mensagem com mais de 255 bytes nas seções. O uso de length_in_bytes como um parâmetro de entrada e um parâmetro de saída permite a codificação de um loop para processar o texto da mensagem inteira. O código a seguir mostra um exemplo de um loop desse tipo, supondo que message_id esteja definido como um identificador de mensagem válido retornado por xp_findnextmsg.

USE master;
GO

-- Set up variables.

DECLARE @status INT,
        @message_part VARCHAR(255),
        @msg_id VARCHAR(255),
        @message_length INT,
        @skip_bytes INT,
        @message VARCHAR(MAX) ;

-- Find the next message

EXEC @status = dbo.xp_findnextmsg
     @msg_id = @msg_id OUTPUT ;


-- If xp_findnextmsg completed successfully and
-- there is a message in the inbox, read the message.

IF (@status = 0  AND @msg_id IS NOT NULL)
BEGIN
   WHILE (1=1)
   BEGIN
        EXEC @status = dbo.xp_readmail
             @msg_id = @msg_id,
             @msg_length = @message_length OUTPUT,
             @skip_bytes = @skip_bytes OUTPUT,
             @message = @message_part OUTPUT ;

        IF @status <> 0 BREAK ;

        SET @message = ISNULL(@message, '') + @message_part ;

        PRINT @message_length ;
        PRINT @skip_bytes;

        IF @message_length = @skip_bytes BREAK ;

    END ;
    
    IF @status = 0
    BEGIN
       SELECT 'Message ID' = @msg_id, 'Message Body' = @message ;
    END ;
    ELSE
        SELECT 'Could not read message.' ;
END;

GO

Permissões

Requer associação na função de servidor fixa sysadmin, mas permissões EXECUTE podem ser concedidas a outros usuários. Mas, por razões de segurança, é recomendável que as permissões desse procedimento armazenado sejam limitadas aos membros da função de servidor fixa sysadmin.

Exemplos

O exemplo a seguir retorna o status ao ler uma mensagem. Neste exemplo, o valor de um ID de mensagem de xp_findnextmsg é colocado na variável local @message_id e passado para xp_readmail.

USE master ;
GO

DECLARE @status INT,
    @msg_id VARCHAR(255),
    @originator VARCHAR(255),
    @cc_list VARCHAR(255),
    @subject VARCHAR(255),
    @query VARCHAR(8000);


-- Find the next message

EXEC @status = dbo.xp_findnextmsg
     @msg_id = @msg_id OUTPUT ;


-- If xp_findnextmsg completed successfully and
-- there is a message in the inbox, read the message.

IF (@status = 0  AND @msg_id IS NOT NULL)
BEGIN
    EXEC @status = dbo.xp_readmail
        @msg_id = @msg_id,
        @originator = @originator OUTPUT,
        @cc_list = @cc_list OUTPUT,
        @subject = @subject OUTPUT,
        @message = @query OUTPUT,
        @peek = 'TRUE',
        @suppress_attach = 'TRUE'

END;
GO

Consulte também

Referência

sp_processmail (Transact-SQL)

Procedimentos armazenados do sistema (Transact-SQL)

xp_deletemail (Transact-SQL)

xp_findnextmsg (Transact-SQL)

xp_sendmail (Transact-SQL)

xp_startmail (Transact-SQL)

xp_stopmail (Transact-SQL)