xp_sendmail (Transact-SQL)

Sintaxe

xp_sendmail { [ @recipients= ] 'recipients [ ;...n ]' } 
     [ ,[ @message= ] 'message' ] 
     [ ,[ @query= ] 'query' ] 
     [ ,[ @attachments= ] 'attachments [ ;...n ]' ] 
     [ ,[ @copy_recipients= ] 'copy_recipients [ ;...n ]'
     [ ,[ @blind_copy_recipients= ] 'blind_copy_recipients [ ;...n ]'
     [ ,[ @subject= ] 'subject' ]
     [ ,[ @type= ] 'type' ] 
     [ ,[ @attach_results= ] 'attach_value' ]
     [ ,[ @no_output= ] 'output_value' ] 
     [ ,[ @no_header= ] 'header_value' ] 
     [ ,[ @width= ] width ] 
     [ ,[ @separator= ] 'separator' ] 
     [ ,[ @echo_error= ] 'echo_value' ] 
     [ ,[ @set_user= ] 'user' ] 
     [ ,[ @dbuse= ] 'database' ]

Argumentos

• [ @recipients=] **'**recipients [ ;... n] '
  É a lista separada por ponto-e-vírgula dos destinatários do email.

• [ @message=] 'message'
  É o corpo da mensagem a ser enviada. message pode ter até 8.000 bytes.

• [ @query=] 'query'
  É uma consulta válida do SQL Server, cujo resultado é enviado em email. xp_sendmail usa uma conexão de saída para o parâmetro query. A conexão query feita pelo SQL Mail não é bloqueada por bloqueios mantidos pelo cliente que emite a solicitação xp_sendmail. Isso torna mais fácil o uso de xp_sendmail em gatilhos. A instrução query, entretanto, não pode se referir às tabelas lógicas inseridas e excluídas, porque elas só estão disponíveis em um gatilho. querypode ter até 8.000 bytes.

• [ @attachments=] **'**attachments [ ;... n] '
  É uma lista separada por ponto-e-vírgula de arquivos a serem anexados à mensagem de email. Se você usar o parâmetro query quando @attach_results for TRUE, o parâmetro @attachments poderá especificar apenas um arquivo a ser anexado à mensagem de email. Nesse caso, para enviar mais de um arquivo, você deve executar xp_sendmail separadamente para cada arquivo fixo.

• [ @copy_recipients=] **'**copy_recipients [ ;... n] '
  É a lista separada por ponto-e-vírgula identificando os destinatários de uma cópia do email.

• [ @blind_copy_recipients=] **'**blind_copy_recipients[ ;... n] '
  É uma lista separada por ponto-e-vírgula opcional identificando os destinatários de uma cópia oculta do email.

• [ @subject=] 'subject'
  É um parâmetro especificando o assunto do email. Se subject não for especificado, o padrão será "SQL Server Message".

• [ @type=] 'type'
  É o tipo da mensagem de entrada com base na definição de email MAPI:

  IP[ M|C ].Vendorname.subclass

  Se type for NULL, xp_sendmail usará um tipo de mensagem de IPM. Os tipos de mensagem que iniciam com IPM aparecem na caixa de entrada do cliente de email e são encontrados ou lidos por xp_findnextmsg. Os tipos de mensagem que iniciam com IPC não aparecem na caixa de entrada do cliente de email e devem ser encontrados ou lidos pela configuração do parâmetro type. O padrão é NULL. O SQL Mail oferece suporte aos tipos de mensagem IPM e IPC.

• [ @attach_results=] 'attach_value'
  É um parâmetro opcional especificando que o conjunto de resultados de uma consulta deve ser enviado em um email como um arquivo anexo, em vez de ser anexado ao email. Se @attachments não for NULL e @attach_results for TRUE, o primeiro nome de arquivo em attachments é usado como o nome de arquivo para os resultados. Se @attachments for NULL, um nome de arquivo é gerado com uma .txt extensão. O padrão é FALSE, o que significa que o conjunto de resultados é anexado à mensagem.

• [ @no_output=] 'output_value'
  É um parâmetro opcional que envia o email mas não retorna nenhuma saída deve à sessão de cliente que enviou o email. O padrão é FALSE, o que significa que a sessão de cliente do SQL Server recebe saída.

• [ @no_header=] 'header_value'
  É um parâmetro opcional que envia os resultados da consulta no email mas não envia as informações de cabeçalho de coluna com os resultados da consulta. O padrão é FALSE, o que significa que as informações de cabeçalho de coluna são enviadas com os resultados da consulta.

• [ @width=] width
  É um parâmetro opcional que define a largura de linha do texto de saída para uma consulta. Este parâmetro é idêntico ao parâmetro /w no utilitário isql. Para obter consultas que produzem longas linhas de saída, use width com attach_results para enviar a saída sem as quebras de linha no meio das linhas de saída. A largura padrão é 80 caracteres.

• [ @separator=] 'separator'
  É a cadeia de caracteres do separador de coluna para cada coluna do conjunto de resultados. Por padrão, o separador de coluna é um espaço em branco. O uso de um separador de coluna permite uma a análise mais fácil do conjunto de resultados em planilhas e outros aplicativos. Por exemplo, use separator com attach_results para enviar arquivos com valores separados por vírgula.

• [ @echo_error=] 'echo_value'
  Quando TRUE, faz o SQL Mail capturar qualquer mensagem de servidor ou erro da DB-Library encontrados ao executar a consulta e anexá-la à mensagem de email em vez de gravá-la no log de erros. Além disso, uma contagem de linhas retornadas/linhas afetadas é anexada à mensagem de email.

  Observação
  Quando echo_error é TRUE, xp_sendmail retorna um status de 0 (êxito) se o email for enviado com êxito, mesmo que erros da DB-Library ou mensagens sejam encontrados ou a consulta não retorne nenhum resultado.

• [ @set_user=] 'user'
  É o contexto de segurança no qual a consulta deve ser executada. Se usuário não for especificado, o contexto de segurança assumirá como padrão o usuário que executa xp_sendmail.

• [ @dbuse=] 'database'
  É o contexto de banco de dados no qual a consulta deve ser executada. O padrão é NULL, o que significa que o usuário é colocado no banco de dados padrão.

Valores de código de retorno

0 (êxito) ou 1 (falha)

Conjuntos de resultados

Quando obtém êxito, xp_sendmail retorna uma mensagem.

Comentários

Uma sessão do SQL Mail deve ser iniciada antes de xp_sendmail ser executado. As sessões podem ser iniciadas automaticamente ou com xp_startmail. Para obter mais informações sobre como configurar uma sessão do SQL Mail automaticamente, consulte Configurando perfis de email de MAPI estendida. Uma sessão do SQL Mail oferece suporte a todos os usuários para a instância do SQL Server, mas somente um usuário por vez pode enviar uma mensagem. Outros usuários que enviam mensagens de email automaticamente esperam sua vez até que a mensagem do primeiro usuário seja enviada.

Se query for especificada, xp_sendmail será registrado no SQL Server como um cliente e executará a consulta especificada. O SQL Mail faz uma conexão separada com o SQL Server; ele não compartilha a mesma conexão que a conexão cliente original que emite xp_sendmail.

Observação

query pode ser bloqueada por um bloqueio mantido pela conexão de cliente que emitiu xp_sendmail. Por exemplo, se você estiver atualizando uma tabela em uma transação e criar um gatilho para atualizar essas tentativas de selecionar as mesmas informações de linha atualizadas como o parâmetro de query, a conexão do SQL Mail será bloqueada pelo bloqueio exclusive mantido na linha pela conexão de cliente inicial.

xp_sendmail é executado no contexto de segurança do SQL Server. Um usuário válido de xp_sendmail pode acessar arquivos a serem anexos em uma mensagem de email no contexto de segurança de um administrador. Se usuários diferentes dos administradores de sistema tiverem de acessar xp_sendmail e você quiser se proteger de acesso inseguro para arquivos anexos, o administrador de sistema poderá criar um procedimento armazenado que chame xp_sendmail e forneça a funcionalidade necessária, mas que não exponha o parâmetro attachments. Esse procedimento armazenado deve ser definido no banco de dados mestre. O administrador de sistema, em seguida, deverá conceder permissão de execução no procedimento armazenado para os usuários necessários sem conceder permissão ao procedimento xp_sendmail subjacente.

xp_sendmail envia uma mensagem e um conjunto de resultados de consulta ou um anexo aos destinatários especificados, e usa uma conexão de saída para o parâmetro query. A conexão query feita pelo SQL Mail não é bloqueada por bloqueios mantidos pelo cliente que emite a solicitação xp_sendmail. Isso torna mais fácil o uso de xp_sendmail em gatilhos. A instrução query, entretanto, não pode se referir às tabelas lógicas inseridas e excluídas que só estão disponíveis em um gatilho.

Observação
Uma violação de acesso pode resultar de uma tentativa de executar xp_sendmail quando a caixa postal e o catálogo de endereços estão em um compartilhamento de arquivos que o serviço do MSSQLServer não pode acessar por causa de permissões inadequadas.

xp_sendmail não oferece suporte total ao tipo de dados xml. As consultas que usam o tipo de dados xml podem ser formatadas incorretamente. Use Database Mail para enviar email que inclua dados xml.

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

A. Enviando uma mensagem para um único destinatário

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @message=N'The master database is full.' ;

B. Enviando uma mensagem a vários destinatários

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com;ashvinis@Adventure-Works.com',
     @message=N'The master database is full.',
     @copy_recipients=N'peterc@Adventure-Works.com',
     @subject=N'Master database status' ;
GO

C. Enviando resultados

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @query = N'EXEC sp_configure' ;
GO

D. Enviando resultados como um arquivo anexo

EXEC master.dbo.xp_sendmail
    @recipients = N'danw@Adventure-Works.com', 
    @query = N'SELECT * FROM INFORMATION_SCHEMA.TABLES',
    @subject = N'SQL Server Report',
    @message = N'The contents of INFORMATION_SCHEMA.TABLES:',
    @attach_results = 'TRUE',
    @width = 250 ;

E. Enviando mensagens com mais de 7.990 bytes de caracteres

CREATE TABLE ##mail_body(c1 NVARCHAR(4000)) ;

DECLARE @cmd VARCHAR(56) ;

INSERT ##mail_body(c1)
VALUES ('Put your long message here.') ;

SET @cmd = 'SELECT c1 FROM ##mail_body' ;

EXEC master.dbo.xp_sendmail 
    @recipients = 'danw@Adventure-Works.com', 
    @query = @cmd,
    @no_header= 'TRUE' ;

DROP TABLE ##mail_body ;

Consulte também

Referência