sp_send_dbmail (Transact-SQL)

Artículo
11/02/2023

Se aplica a:SQL Server Azure SQL Managed Instance

Envía un mensaje de correo electrónico a los destinatarios especificados. El mensaje puede incluir un conjunto de resultados de consulta, datos adjuntos de archivo o ambos. Cuando el correo se coloca correctamente en la cola de Correo electrónico de base de datos, sp_send_dbmail devuelve el mailitem_id del mensaje. Este procedimiento almacenado se encuentra en la msdb base de datos.

Convenciones de sintaxis de Transact-SQL

Sintaxis

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 = ] N'subject' ]
    [ , [ @body = ] N'body' ]
    [ , [ @body_format = ] 'body_format' ]
    [ , [ @importance = ] 'importance' ]
    [ , [ @sensitivity = ] 'sensitivity' ]
    [ , [ @file_attachments = ] N'attachment [ ; ...n ]' ]
    [ , [ @query = ] N'query' ]
    [ , [ @execute_query_database = ] 'execute_query_database' ]
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]
    [ , [ @query_attachment_filename = ] N'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'

Nombre del perfil desde el que se va a enviar el mensaje. El @profile_name es de tipo sysname, con un valor predeterminado de NULL. El @profile_name debe ser el nombre de un perfil de Correo electrónico de base de datos existente. Cuando no se especifica ningún @profile_name , sp_send_dbmail usa el perfil privado predeterminado para el usuario actual. Si el usuario no tiene un perfil privado predeterminado, sp_send_dbmail usa el perfil público predeterminado para la msdb base de datos. Si el usuario no tiene un perfil privado predeterminado y no hay ningún perfil público predeterminado para la base de datos, se debe especificar @profile_name .

[ @recipients = ] 'recipients'

Lista delimitada por punto y coma de direcciones de correo electrónico a las que se va a enviar el mensaje. La lista de destinatarios es de tipo varchar(max). Aunque este parámetro es opcional, se debe especificar al menos uno de @recipients, @copy_recipients o @blind_copy_recipients , o sp_send_dbmail devuelve un error.

[ @copy_recipients = ] 'copy_recipients'

Una lista delimitada por punto y coma de direcciones de correo electrónico a la que copiar el mensaje. La lista de destinatarios de copia es de tipo varchar(max). Aunque este parámetro es opcional, se debe especificar al menos uno de @recipients, @copy_recipients o @blind_copy_recipients , o sp_send_dbmail devuelve un error.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Una lista delimitada por punto y coma de direcciones de correo electrónico para copiar el mensaje en carbono ciego. La lista de destinatarios de copia ciega es de tipo varchar(max). Aunque este parámetro es opcional, se debe especificar al menos uno de @recipients, @copy_recipients o @blind_copy_recipients , o sp_send_dbmail devuelve un error.

[ @from_address = ] 'from_address'

Valor de "from address" del mensaje de correo electrónico. Se trata de un parámetro opcional que se usa para invalidar la configuración del perfil de correo. Este parámetro es de tipo varchar(max). La configuración de seguridad de SMTP determina si se aceptan estas invalidaciones. Si no se especifica ningún parámetro, el valor predeterminado es NULL.

[ @reply_to = ] 'reply_to'

Valor de la "respuesta a la dirección" del mensaje de correo electrónico. Solo acepta una dirección de correo electrónico como valor válido. Se trata de un parámetro opcional que se usa para invalidar la configuración del perfil de correo. Este parámetro es de tipo varchar(max). La configuración de seguridad de SMTP determina si se aceptan estas invalidaciones. Si no se especifica ningún parámetro, el valor predeterminado es NULL.

[ @subject = ] N'subject'

Asunto del mensaje de correo electrónico. El asunto es de tipo nvarchar(255). Si no se especifica ningún asunto, el valor predeterminado es 'Mensaje de SQL Server'.

[ @body = ] N'body'

Cuerpo del mensaje de correo electrónico. El cuerpo del mensaje es de tipo nvarchar(max), con un valor predeterminado de NULL.

[ @body_format = ] 'body_format'

Formato del cuerpo del mensaje. El parámetro es de tipo varchar(20), con un valor predeterminado de NULL. Si se especifica, los encabezados del mensaje saliente indican que el cuerpo del mensaje tiene el formato especificado. El parámetro puede contener uno de los siguientes valores:

TEXT (valor predeterminado)
HTML

[ @importance = ] 'importance'

Importancia del mensaje. El parámetro es de tipo varchar(6). El parámetro puede contener uno de los siguientes valores:

Low
Normal (valor predeterminado)
High

[ @sensitivity = ] 'sensitivity'

Sensibilidad del mensaje. El parámetro es de tipo varchar(12). El parámetro puede contener uno de los siguientes valores:

Normal (valor predeterminado)
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

Lista delimitada por punto y coma de nombres de archivo que se van a adjuntar al mensaje de correo electrónico. Especifique los archivos de la lista como rutas de acceso absolutas. La lista de datos adjuntos es de tipo nvarchar(max). De forma predeterminada, Correo electrónico de base de datos limita los datos adjuntos a 1 MB por archivo.

Importante

Este parámetro no está disponible en Azure SQL Instancia administrada, ya que no puede acceder al sistema de archivos local.

[ @query = ] N'query'

Una consulta que se va a ejecutar. Los resultados de la consulta pueden adjuntarse como archivo o incluirse en el cuerpo del mensaje de correo electrónico. La consulta es de tipo nvarchar(max)y puede contener cualquier instrucción Transact-SQL válida. La consulta se ejecuta en una sesión independiente, por lo que las variables locales de la llamada sp_send_dbmail de script no están disponibles para la consulta.

Cuando se usa el parámetro @query , la entidad de seguridad que se sp_send_dbmail ejecuta debe estar conectada como individual, no como parte de un grupo, ya sea un identificador de Microsoft Entra (anteriormente Azure Active Directory) o un grupo de Windows Active Directory. Los inicios de sesión de SQL Server, las identidades de Windows y las identidades de Microsoft Entra pueden ejecutar la consulta, pero los miembros del grupo no pueden, debido a las limitaciones de suplantación y ejecución de Azure SQL Instancia administrada.

[ @execute_query_database = ] 'execute_query_database'

Contexto de base de datos en el que el procedimiento almacenado ejecuta la consulta. El parámetro es de tipo sysname, con un valor predeterminado de la base de datos actual. Este parámetro solo es aplicable si se especifica @query .

[ @attach_query_result_as_file = ] attach_query_result_as_file

Especifica si el conjunto de resultados de la consulta se devuelve como un dato adjunto. @attach_query_result_as_file es de tipo bit, con un valor predeterminado de 0.

Cuando el valor es 0, los resultados de la consulta se incluyen en el cuerpo del mensaje de correo electrónico, después del contenido del parámetro @body . Cuando el valor es 1, los resultados se devuelven como datos adjuntos. Este parámetro solo es aplicable si se especifica @query .

[ @query_attachment_filename = ] N'query_attachment_filename'

Especifica el nombre del archivo que se va a utilizar para el conjunto de resultados de los datos adjuntos de la consulta. @query_attachment_filename es de tipo nvarchar(255), con un valor predeterminado de NULL. Este parámetro se omite cuando @attach_query_result_as_file es 0. Cuando @attach_query_result_as_file es y este parámetro es 1NULL, Correo electrónico de base de datos crea un nombre de archivo arbitrario.

[ @query_result_header = ] query_result_header

Especifica si los resultados de la consulta van a incluir encabezados de columna. El valor query_result_header es de tipo bit. Cuando el valor es 1, los resultados de la consulta contienen encabezados de columna. Cuando el valor es 0, los resultados de la consulta no incluyen encabezados de columna. Este parámetro tiene 1como valor predeterminado . Este parámetro solo es aplicable si se especifica @query .

Es posible que se produzca el siguiente error al establecer @query_result_header0 en y establecer @query_no_truncate en1:

Msg 22050, Level 16, State 1, Line 12: Failed to initialize sqlcmd library with error number -2147024809.

[ @query_result_width = ] query_result_width

Ancho de línea, en caracteres, que se va a usar para dar formato a los resultados de la consulta. El @query_result_width es de tipo int, con un valor predeterminado de 256. El valor proporcionado debe estar entre 10 y 32767. Este parámetro solo es aplicable si se especifica @query .

[ @query_result_separator = ] 'query_result_separator'

Carácter utilizado para separar columnas en la salida de la consulta. El separador es de tipo char(1). El valor predeterminado es ' ' (espacio).

[ @exclude_query_output = ] exclude_query_output

Especifica si se debe devolver la salida de la ejecución de la consulta en el mensaje de correo electrónico. @exclude_query_output es bit, con un valor predeterminado de 0. Cuando este parámetro es 0, la ejecución del sp_send_dbmail procedimiento almacenado imprime el mensaje devuelto como resultado de la ejecución de la consulta en la consola. Cuando este parámetro es 1, la ejecución del sp_send_dbmail procedimiento almacenado no imprime ninguno de los mensajes de ejecución de consultas en la consola.

[ @append_query_error = ] append_query_error

Especifica si se debe enviar el correo electrónico cuando se devuelve un error de la consulta especificada en el argumento @query . @append_query_error es bit, con un valor predeterminado de 0. Cuando este parámetro es 1, Correo electrónico de base de datos envía el mensaje de correo electrónico e incluye el mensaje de error de consulta en el cuerpo del mensaje de correo electrónico. Cuando este parámetro es 0, Correo electrónico de base de datos no envía el mensaje de correo electrónico y sp_send_dbmail termina con el código 1de retorno , lo que indica un error.

[ @query_no_truncate = ] query_no_truncate

Especifica si se debe ejecutar la consulta con la opción que evita el truncamiento de tipos de datos de longitud variable grande (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image y tipos de datos definidos por el usuario. Cuando se establece, los resultados de la consulta no incluyen encabezados de columna. El valor @query_no_truncate es de tipo bit. Cuando se 0 especifica o no el valor, las columnas de la consulta se truncan en 256 caracteres. Cuando el valor es 1, las columnas de la consulta no se truncan. Este parámetro tiene 0como valor predeterminado .

Nota:

Cuando se usa con grandes cantidades de datos, la opción @query_no_truncate consume recursos adicionales y puede ralentizar el rendimiento del servidor.

[ @query_result_no_padding = ] query_result_no_padding

El tipo es bit. El valor predeterminado es 0. Cuando se establece en 1, los resultados de la consulta no se rellenan, lo que puede reducir el tamaño del archivo. Si establece @query_result_no_padding1 en y establece el parámetro @query_result_width , el parámetro @query_result_no_padding sobrescribe el parámetro @query_result_width .

En este caso, no se produce ningún error.

Es posible que se produzca el siguiente error al establecer @query_result_no_padding 1 en y proporcionar un parámetro para @query_no_truncate:

Msg 22050, Level 16, State 1, Line 0: Failed to execute the query because the @query_result_no_append and @query_no_truncate options are mutually exclusive.

Si establece el @query_result_no_padding1 en y establece el parámetro @query_no_truncate , se produce un error.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

El parámetro de salida opcional devuelve el mailitem_id del mensaje. @mailitem_id es de tipo int.

Valores de código de retorno

Código devuelto de 0 significa correcto. Cualquier otro valor significa error. El código de error de la instrucción que produjo un error se almacena en la @@ERROR variable .

Conjunto de resultados

Si se ejecuta correctamente, devuelve el mensaje "Correo en cola".

Comentarios

Antes de usarlo, Correo electrónico de base de datos debe habilitarse mediante el Asistente para configuración de Correo electrónico de base de datos o sp_configure.

sysmail_stop_spdetiene Correo electrónico de base de datos deteniendo los objetos de Service Broker que usa el programa externo. sp_send_dbmailsigue aceptando el correo cuando Correo electrónico de base de datos se detiene mediante sysmail_stop_sp. Para iniciar Correo electrónico de base de datos, use sysmail_start_sp.

Cuando no se especifica @profile , sp_send_dbmail usa un perfil predeterminado. Si el usuario que envía el mensaje de correo electrónico tiene un perfil privado predeterminado, el Correo electrónico de base de datos utilizará dicho perfil. Si el usuario no tiene ningún perfil privado predeterminado, sp_send_dbmail usa el perfil público predeterminado. Si no hay ningún perfil privado predeterminado para el usuario y ningún perfil público predeterminado, sp_send_dbmail devuelve un error.

sp_send_dbmail no admite mensajes de correo electrónico sin contenido. Para enviar un mensaje de correo electrónico, debe especificar al menos una de @body, @query, @file_attachments o @subject. De lo contrario, sp_send_dbmail devuelve un error.

Correo electrónico de base de datos usa el contexto de seguridad de Microsoft Windows del usuario actual para controlar el acceso a los archivos. Por lo tanto, los usuarios que se autentican con la autenticación de SQL Server no pueden adjuntar archivos mediante @file_attachments. Windows no permite que SQL Server proporcione credenciales desde un equipo remoto a otro equipo remoto. Por lo tanto, es posible que Correo electrónico de base de datos no puedan adjuntar archivos desde un recurso compartido de red en casos en los que el comando se ejecuta desde un equipo distinto del equipo en el que se ejecuta SQL Server.

Si se especifican tanto @querycomo @file_attachments y no se encuentra el archivo, la consulta todavía se ejecuta pero no se envía el correo electrónico.

Cuando se especifica una consulta, el conjunto de resultados se formatea como texto insertado. Los datos binarios del conjunto de resultados se envían en formato hexadecimal.

Los parámetros @recipients, @copy_recipients y @blind_copy_recipients son listas delimitadas por punto y coma de direcciones de correo electrónico. Se debe proporcionar al menos uno de estos parámetros o sp_send_dbmail devuelve un error.

Al ejecutar sp_send_dbmail sin un contexto de transacción, Correo electrónico de base de datos inicia y confirma una transacción implícita. Al ejecutar sp_send_dbmail desde dentro de una transacción existente, Correo electrónico de base de datos se basa en el usuario para confirmar o revertir los cambios. No inicia una transacción interna.

Permisos

Ejecute los permisos de forma predeterminada para sp_send_dbmail todos los miembros del rol de base de datos DatabaseMailUser de la msdb base de datos. Sin embargo, cuando el usuario que envía el mensaje no tiene permiso para usar el perfil de la solicitud, sp_send_dbmail devuelve un error y no envía el mensaje.

Ejemplos

A Enviar un mensaje de correo electrónico

En este ejemplo se envía un mensaje de correo electrónico a su amigo mediante la dirección myfriend@adventure-works.comde correo electrónico . El asunto del mensaje es Automated Success Message. El cuerpo del mensaje contiene la frase The stored procedure finished successfully.

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

B. Enviar un mensaje de correo electrónico con los resultados de una consulta

En este ejemplo se envía un mensaje de correo electrónico a su amigo mediante la dirección yourfriend@adventure-works.comde correo electrónico . El mensaje tiene el asunto Work Order County ejecuta una consulta que muestra el número de pedidos de trabajo con menos DueDate de dos días después del 30 de abril de 2022. El Correo electrónico de base de datos adjunta el resultado como archivo de texto.

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

C. Enviar un mensaje de correo electrónico HTML

En este ejemplo se envía un mensaje de correo electrónico a su amigo mediante la dirección yourfriend@adventure-works.comde correo electrónico . El mensaje tiene el asunto Work Order Listy contiene un documento HTML que muestra los pedidos de trabajo con menos DueDate de dos días después del 30 de abril de 2022. El Correo electrónico de base de datos envía el mensaje en 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
            INNER JOIN AdventureWorks.Production.Product AS p
                ON wo.ProductID = p.ProductID
            WHERE DueDate > '2022-04-30'
                AND DATEDIFF(dd, '2022-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 = 'yourfriend@adventure-works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML';

sp_send_dbmail (Transact-SQL)

Sintaxis

Argumentos

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @from_address = ] 'from_address'

[ @reply_to = ] 'reply_to'

[ @subject = ] N'subject'

[ @body = ] N'body'

[ @body_format = ] 'body_format'

[ @importance = ] 'importance'

[ @sensitivity = ] 'sensitivity'

[ @file_attachments = ] N'file_attachments'

[ @query = ] N'query'

[ @execute_query_database = ] 'execute_query_database'

[ @attach_query_result_as_file = ] attach_query_result_as_file

[ @query_attachment_filename = ] N'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 ]

Valores de código de retorno

Conjunto de resultados

Comentarios

Permisos

Ejemplos

A Enviar un mensaje de correo electrónico

B. Enviar un mensaje de correo electrónico con los resultados de una consulta

C. Enviar un mensaje de correo electrónico HTML

Contenido relacionado

Comentarios

Comentarios

Recursos adicionales