xp_sendmail (Transact-SQL)
Envia uma mensagem de email, que pode incluir um anexo de conjunto de resultados da consulta, aos destinatários especificados. Este procedimento armazenado estendido usa o SQL Mail para enviar a mensagem.
.gif "Observação") 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. Para enviar email do SQL Server, use o Database Mail. |
.gif "Ícone de vínculo de tópico")
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çãoQuando 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
O exemplo a seguir envia uma mensagem ao usuário Dan Wilson (o email é danw) de que o banco de dados master está cheio.
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
O exemplo a seguir envia a mensagem aos usuários Dan Wilson e Ashvini Sharma (o email é ashvinis) com uma cópia enviada a Peter Connelly (o email é peterc). O exemplo também especifica uma linha de assunto para a mensagem.
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
O exemplo a seguir envia os resultados de sp_configure a Dan Wilson.
EXEC master.dbo.xp_sendmail
@recipients=N'danw@Adventure-Works.com',
@query = N'EXEC sp_configure' ;
GO
D. Enviando resultados como um arquivo anexo
O exemplo a seguir envia os resultados da consulta SELECT * FROM INFORMATION_SCHEMA.TABLES como um anexo de arquivo de texto para Dan Wilson. O exemplo inclui uma linha de assunto para o email e uma mensagem que aparecerá antes do anexo. O parâmetro @width é usado para evitar quebras de linha nas linhas de saída.
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
O exemplo a seguir mostra como enviar uma mensagem com mais de 7.990 bytes de caracteres. Como message está limitada ao comprimento de um VARCHAR (menos sobrecarga de linha, como em todos os parâmetros de procedimento armazenado), este exemplo grava a mensagem longa em uma tabela temporária global composta de uma única coluna de texto. Os conteúdos dessa tabela temporária são enviados em um email usando o parâmetro @query.
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 ;