sp_send_dbmail (Transact-SQL)

Envia uma mensagem de email aos destinatários especificados. A mensagem pode incluir um conjunto de resultados da consulta, anexos de arquivo ou ambos. Quando o email é colocado com êxito na fila do Database Mail, sp_send_dbmail retorna o mailitem_id da mensagem. Este procedimento armazenado está no banco de dados msdb.

Convenções da sintaxe Transact-SQL

Sintaxe

sp_send_dbmail [ [ @profile_name = ] 'profile_name' ]
    [ , [ @recipients = ] 'recipients [ ; ...n ]' ]
    [ , [ @copy_recipients = ] 'copy_recipient [ ; ...n ]' ]
    [ , [ @blind_copy_recipients = ] 'blind_copy_recipient [ ; ...n ]' ]
    [ , [ @from_address = ] 'from_address' ]
    [ , [ @reply_to = ] 'reply_to' ] 
    [ , [ @subject = ] 'subject' ] 
    [ , [ @body = ] 'body' ] 
    [ , [ @body_format = ] 'body_format' ]
    [ , [ @importance = ] 'importance' ]
    [ , [ @sensitivity = ] 'sensitivity' ]
    [ , [ @file_attachments = ] 'attachment [ ; ...n ]' ]
    [ , [ @query = ] 'query' ]
    [ , [ @execute_query_database = ] 'execute_query_database' ]
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]
    [ , [ @query_attachment_filename = ] query_attachment_filename ]
    [ , [ @query_result_header = ] query_result_header ]
    [ , [ @query_result_width = ] query_result_width ]
    [ , [ @query_result_separator = ] 'query_result_separator' ]
    [ , [ @exclude_query_output = ] exclude_query_output ]
    [ , [ @append_query_error = ] append_query_error ]
    [ , [ @query_no_truncate = ] query_no_truncate ] 
…………[ , [@query_result_no_padding = ] @query_result_no_padding ] 
    [ , [ @mailitem_id = ] mailitem_id ] [ OUTPUT ]

Argumentos

• [ @profile_name= ] 'profile_name'
  É o nome do perfil do qual a mensagem será enviada. O profile_name é do tipo sysname, com um padrão NULL. O profile_name deve ser o nome de um perfil existente do Database Mail. Quando nenhum profile_name é especificado, sp_send_dbmail usa o perfil particular padrão para o usuário atual. Se o usuário não tiver nenhum perfil particular padrão, sp_send_dbmail usará o perfil público padrão para o banco de dados msdb. Se o usuário não tiver um perfil particular padrão e não houver um perfil público padrão para o banco de dados, @profile_name deverá ser especificado.

• [ @recipients= ] 'recipients'
  É uma lista delimitada por ponto-e-vírgula de endereços de email aos quais a mensagem será enviada. A lista de destinatários é do tipo varchar(max). Embora esse parâmetro seja opcional, pelo menos um dos @recipients, @copy_recipients ou @blind_copy_recipients deve ser especificado, caso contrário, sp_send_dbmail retornará um erro.

• [ @copy_recipients= ] 'copy_recipients'
  É uma lista delimitada por ponto-e-vírgula de endereços de email aos quais será enviada uma cópia carbono da mensagem. A lista de destinatários de cópia é do tipo varchar(max). Embora esse parâmetro seja opcional, pelo menos um dos @recipients, @copy_recipients ou @blind_copy_recipients deve ser especificado, caso contrário, sp_send_dbmail retornará um erro.

• [ @blind_copy_recipients= ] 'blind_copy_recipients'
  É uma lista delimitada por ponto-e-vírgula de endereços de email aos quais será enviada uma cópia carbono oculta da mensagem. A lista de destinatários de cópia oculta é do tipo varchar(max). Embora esse parâmetro seja opcional, pelo menos um dos @recipients, @copy_recipients ou @blind_copy_recipients deve ser especificado, caso contrário, sp_send_dbmail retornará um erro.

• [ @from_address= ] 'from_address'
  É o valor do 'endereço de origem' da mensagem de email. Esse é um parâmetro opcional usado para substituir as configurações no perfil de email. Este parâmetro é do tipo varchar(MAX). As configurações de segurança de SMTP determinarão se essas substituições serão aceitas. Se nenhum parâmetro for especificado, o padrão será NULL.

• [ @reply_to= ] 'reply_to'
  É o valor do 'endereço de resposta' da mensagem de email. Aceita apenas um endereço de email como um valor válido. Esse é um parâmetro opcional usado para substituir as configurações no perfil de email. Este parâmetro é do tipo varchar(MAX). As configurações de segurança de SMTP determinarão se essas substituições serão aceitas. Se nenhum parâmetro for especificado, o padrão será NULL.

• [ @subject= ] 'subject'
  É o assunto da mensagem de email. O assunto é do tipo nvarchar(255). Se nenhum assunto for especificado, o padrão será 'SQL Server Message'.

• [ @body= ] 'body'
  É o corpo da mensagem de email. O corpo da mensagem é do tipo nvarchar(max), com um padrão NULL.

• [ @body_format= ] 'body_format'
  É o formato do corpo da mensagem. O parâmetro é do tipo varchar(20) com um padrão NULL. Quando especificado, os cabeçalhos da mensagem de saída são definidos para indicar que o corpo da mensagem tem o formato especificado. O parâmetro pode conter um dos seguintes valores:

  • TEXT

  • HTML

  Assume TEXT como padrão.

• [ @importance= ] 'importance'
  É a importância da mensagem. O parâmetro é do tipo varchar(6). O parâmetro pode conter um dos seguintes valores:

  • Baixo

  • Normal

  • Alto

  Assume Normal como padrão.

• [ @sensitivity= ] 'sensitivity'
  É a sensibilidade da mensagem. O parâmetro é do tipo varchar(12). O parâmetro pode conter um dos seguintes valores:

  • Normal

  • Personal

  • Privado

  • Confidential

  Assume Normal como padrão.

• [ @file_attachments= ] 'file_attachments'
  É uma lista delimitada por ponto-e-vírgula de nomes de arquivo a ser anexada à mensagem de email. Os arquivos da lista devem ser especificados como caminhos absolutos. A lista de anexos é do tipo nvarchar(max). Por padrão, o Database Mail limita os anexos de arquivo a 1 MB por arquivo.

• [ @query= ] 'query'
  É uma consulta a ser executada. Os resultados da consulta podem ser anexados a um arquivo ou incluídos no corpo da mensagem de email. A consulta é do tipo nvarchar(max) e pode conter qualquer instrução Transact-SQL válida. Observe que a consulta é executada em uma sessão separada, portanto, as variáveis locais no script que chamam sp_send_dbmail não estão disponíveis para a consulta.

• [ @execute_query_database= ] 'execute_query_database'
  É o contexto de banco de dados dentro do qual o procedimento armazenado executa a consulta. O parâmetro é do tipo sysname, com um padrão do banco de dados atual. Esse parâmetro só é aplicável se @query for especificado.

• [ @attach_query_result_as_file= ] attach_query_result_as_file
  Especifica se o conjunto de resultados da consulta é retornado como um arquivo anexado. attach_query_result_as_file é do tipo bit, com um padrão de 0.

  Quando o valor é 0, os resultados da consulta são incluídos no corpo da mensagem de email, depois do conteúdo do parâmetro @body . Quando o valor é 1, os resultados são retornados como um anexo. Esse parâmetro só é aplicável se @query for especificado.

• [ @query_attachment_filename= ] query_attachment_filename
  Especifica o nome do arquivo a ser usado para o conjunto de resultados do anexo da consulta. query_attachment_filename é do tipo nvarchar(255), com um padrão de NULL. Este parâmetro é ignorado quando attach_query_result é 0. Quando attach_query_result é 1 e esse parâmetro é NULL, o Database Mail cria um nome de arquivo arbitrário.

• [ @query_result_header= ] query_result_header
  Especifica se os resultados da consulta incluem cabeçalhos de coluna. O valor query_result_header é do tipo bit. Quando o valor é 1, os resultados da consulta contêm cabeçalhos de coluna. Quando o valor é 0, resultados da consulta não incluem cabeçalhos de coluna. Esse parâmetro assume 1 como padrão. Esse parâmetro só é aplicável se @query for especificado.

• [ @query_result_width = ] query_result_width
  É a largura de linha, em caracteres, a ser usada para formatar os resultados da consulta. O query_result_width é do tipo int, com um padrão de 256. O valor fornecido deve estar entre 10 e 32767. Esse parâmetro só é aplicável se @query for especificado.

• [ @query_result_separator= ] 'query_result_separator'
  É o caractere usado para separar as colunas na saída da consulta. O separador é do tipo char(1). Usa como padrão ' ' (espaço).

• [ @exclude_query_output= ] exclude_query_output
  Especifica se a saída da execução da consulta deve ser retornada na mensagem de email exclude_query_output é bit, com um padrão de 0. Quando esse parâmetro é 0, a execução do procedimento armazenado sp_send_dbmail imprime a mensagem retornada como o resultado da execução da consulta no console. Quando esse parâmetro é 1, a execução do procedimento armazenado sp_send_dbmail não imprime nenhuma mensagem de execução de consulta no console.

• [ @append_query_error= ] append_query_error
  Especifica se deve ser enviado um email quando for retornado um erro da consulta especificada no argumento @query. append_query_error é bit, com um padrão de 0. Quando esse parâmetro é 1, o Database Mail envia a mensagem de email e inclui a mensagem de erro de consulta no corpo da mensagem de email. Quando esse parâmetro é 0, o Database Mail não envia a mensagem de email e sp_send_dbmail encerra com o código de retorno 1, indicando falha.

• [ @query_no_truncate= ] query_no_truncate
  Especifica se a consulta deve ser executada com a opção que evita truncamento de tipos de dados de comprimento de variável grande (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image e tipos de dados definidos pelo usuário). Quando definido, os resultados da consulta não incluem cabeçalhos de coluna. O valor de query_no_truncate é do tipo bit. Quando o valor é 0 ou não especificado, as colunas na consulta são truncadas com 256 caracteres. Quando o valor é 1, as colunas da consulta não são truncadas. Esse parâmetro assume 0 como padrão.

  Observação
  Quando usado com grandes quantidades de dados, a opção @query_no_truncate consome recursos adicionais e pode reduzir o desempenho do servidor.

• [ @query_result_no_padding ] @query\_result\_no\_padding
  O tipo é bit. O padrão é 0. Quando você o define como 1, os resultados da consulta não são preenchidos, possivelmente reduzindo o tamanho do arquivo. Se você definir @query\_result\_no\_padding como 1 e definir o parâmetro @query\_result\_width, o parâmetro @query\_result\_no\_padding substituirá o parâmetro @query\_result\_width.

  Nesse caso, não ocorre nenhum erro.

  Se você definir o @query\_result\_no\_padding como 1 e definir o parâmetro @query\_no\_truncate, será gerado um erro.

• [ @mailitem_id= ] mailitem_id [ OUTPUT ]
  O parâmetro de saída opcional retorna a mailitem_id da mensagem. O mailitem_id é do tipo int.

Valores de código de retorno

Um código de retorno de 0 significa êxito. Qualquer outro valor significa falha. O código de erro para a instrução que falhou é armazenado na variável @@ERRROR.

Conjuntos de resultados

Com êxito, retorna a mensagem que "Email enfileirado".

Comentários

Antes de ser usado, o Database Mail deve ser habilitado no Assistente para Configuração do Database Mail ou usando sp_configure.

sysmail_stop_sp interrompe o Database Mail com a interrupção de objetos do Service Broker usados pelo programa externo. sp_send_dbmail ainda aceita email quando Database Mail é interrompido com sysmail_stop_sp. Para iniciar o Database Mail, use sysmail_start_sp.

Quando @profile não é especificado, sp_send_dbmail usa um perfil padrão. Se o usuário que envia a mensagem de email tiver um perfil particular padrão, o Database Mail irá utilizá-lo. Se o usuário não tiver nenhum perfil particular padrão, o sp_send_dbmail usará o perfil público padrão. Se não houver nenhum perfil particular padrão para o usuário e nenhum perfil público padrão, o sp_send_dbmail retornará um erro.

sp_send_dbmail não aceita mensagens de email sem conteúdo. Para enviar uma mensagem de email, é necessário especificar pelo menos um @body, @query, @file_attachments ou @subject. Caso contrário, sp_send_dbmail retornará um erro.

O Database Mail usa o contexto de segurança do usuário atual do Microsoft Windows para controlar o acesso a arquivos. Portanto, os usuários autenticados com a Autenticação do SQL Server não podem anexar arquivos usando @file_attachments. O Windows não permite que o SQL Server forneça credenciais de um computador remoto para outro. Portanto, o Database Mail pode não conseguir anexar arquivos de um compartilhamento de rede caso o comando seja executado de um computador diferente daquele em que o SQL Server é executado.

Se @query e @file_attachments forem especificados e o arquivo não for localizado, a consulta ainda será executada mas o email não será enviado.

Quando uma consulta é especificada, o conjunto de resultados é formatado como texto em linha. Dados binários no resultado são enviados em formato hexadecimal.

Os parâmetros @recipients, @copy_recipients e @blind_copy_recipients são listas delimitadas por ponto-e-vírgula de endereços de email. Pelo menos um desses parâmetros deve ser fornecido ou sp_send_dbmail retornará um erro.

Ao executar sp_send_dbmail sem um contexto de transação, o Database Mail inicia e confirma uma transação implícita. Ao executar sp_send_dbmail de uma transação existente, o Database Mail depende do usuário para confirmar ou reverter qualquer alteração. Ele não inicia uma transação interna.

Permissões

Permissões de execução para sp_send_dbmail assumem como padrão todos os membros da função de banco de dados DatabaseMailUser no banco de dados msdb. Entretanto, quando o usuário que está enviando a mensagem não tem permissão para usar o perfil para a solicitação, sp_send_dbmail retorna um erro e não envia a mensagem.

Exemplos

A.Enviando uma mensagem de email

Este exemplo envia uma mensagem de email a Dan Wilson usando o endereço de email danw@Adventure-Works.com. O assunto da mensagem é Automated Success Message. O corpo da mensagem contém a sentença 'The stored procedure finished successfully'.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @body = 'The stored procedure finished successfully.',
    @subject = 'Automated Success Message' ;

B.Enviando uma mensagem de email com os resultados de uma consulta

Este exemplo envia uma mensagem de email a Dan Wilson usando o endereço de email danw@Adventure-Works.com. O assunto da mensagem é Work Order Count e executa uma consulta que mostra o número de ordens de trabalho com uma DueDate menor que dois dias, após 30 de abril de 2004. O Database Mail anexa o resultado como um arquivo de texto.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2012.Production.WorkOrder
                  WHERE DueDate > ''2004-04-30''
                  AND  DATEDIFF(dd, ''2004-04-30'', DueDate) < 2' ,
    @subject = 'Work Order Count',
    @attach_query_result_as_file = 1 ;

C.Enviando uma mensagem de email HTML

Este exemplo envia uma mensagem de email a Dan Wilson usando o endereço de email danw@Adventure-Works.com. O assunto da mensagem é Work Order List e contém um documento HTML que mostra o número de ordens de trabalho com uma DueDate menor que dois dias, após 30 de abril de 2004. O Database Mail envia a mensagem no formato HTML.

DECLARE @tableHTML  NVARCHAR(MAX) ;

SET @tableHTML =
    N'<H1>Work Order Report</H1>' +
    N'<table border="1">' +
    N'<tr><th>Work Order ID</th><th>Product ID</th>' +
    N'<th>Name</th><th>Order Qty</th><th>Due Date</th>' +
    N'<th>Expected Revenue</th></tr>' +
    CAST ( ( SELECT td = wo.WorkOrderID,       '',
                    td = p.ProductID, '',
                    td = p.Name, '',
                    td = wo.OrderQty, '',
                    td = wo.DueDate, '',
                    td = (p.ListPrice - p.StandardCost) * wo.OrderQty
              FROM AdventureWorks.Production.WorkOrder as wo
              JOIN AdventureWorks.Production.Product AS p
              ON wo.ProductID = p.ProductID
              WHERE DueDate > '2004-04-30'
                AND DATEDIFF(dd, '2004-04-30', DueDate) < 2 
              ORDER BY DueDate ASC,
                       (p.ListPrice - p.StandardCost) * wo.OrderQty DESC
              FOR XML PATH('tr'), TYPE 
    ) AS NVARCHAR(MAX) ) +
    N'</table>' ;

EXEC msdb.dbo.sp_send_dbmail @recipients='danw@Adventure-Works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML' ;

Consulte também

Referência

Procedimentos armazenados do Database Mail (Transact-SQL)

sp_addrolemember (Transact-SQL)

Conceitos

Database Mail

Objetos de configuração do Database Mail