sp_send_dbmail (Transact-SQL)

Artículo
06/18/2013

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

Icono de vínculo a temas 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 = ] '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'
Nombre del perfil desde el que se va a enviar el mensaje. profile_name es de tipo sysname y su valor predeterminado es NULL. profile_name debe ser el nombre de un perfil existente de Correo electrónico de base de datos. Si no se especifica profile_name, sp_send_dbmail utiliza el perfil privado predeterminado del usuario actual. Si el usuario no tiene un perfil privado predeterminado, sp_send_dbmail utiliza el perfil público predeterminado de la base de datos msdb. Si el usuario no tiene un perfil privado predeterminado y no hay ningún perfil público predeterminado para la base de datos, debe especificarse @profile_name.
[ @recipients= ] 'recipients'
Lista de direcciones de correo electrónico, separadas por punto y coma, a las que se va a enviar el mensaje. La lista de destinatarios es de tipo varchar(max). Aunque este parámetro es opcional, debe especificarse como mínimo uno de los valores @recipients, @copy_recipients o @blind_copy_recipients, de lo contrario sp_send_dbmail devuelve un error.
[ @copy_recipients= ] 'copy_recipients'
Lista de direcciones de correo electrónico, separadas por punto y coma, que van a recibir copia del mensaje. La lista de destinatarios que recibirán copia es de tipo varchar(max). Aunque este parámetro es opcional, debe especificarse como mínimo uno de los valores @recipients, @copy_recipients o @blind_copy_recipients, de lo contrario sp_send_dbmail devuelve un error.
[ @blind_copy_recipients= ] 'blind_copy_recipients'
Lista de direcciones de correo electrónico, separadas por punto y coma, que van a recibir copia oculta del mensaje. La lista de destinatarios de la copia oculta es de tipo varchar(max). Aunque este parámetro es opcional, debe especificarse como mínimo uno de los valores @recipients, @copy_recipients o @blind_copy_recipients, de lo contrario sp_send_dbmail devuelve un error.
[ @from_address= ] 'from_address'
Valor del parámetro '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 del parámetro 'reply to address' 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= ] '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= ] 'body'
Cuerpo del mensaje de correo electrónico. El cuerpo del mensaje es de tipo nvarchar(max) y su valor predeterminado es NULL.
[ @body_format= ] 'body_format'
Formato del cuerpo del mensaje. El parámetro es de tipo varchar(20) y su valor predeterminado es 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
- HTML
El valor predeterminado es TEXT.
[ @importance= ] 'importance'
Hace referencia a la importancia del mensaje. El parámetro es de tipo varchar(6). El parámetro puede contener uno de los siguientes valores:
- Low
- Normal
- High
El valor predeterminado es Normal.
[ @sensitivity= ] 'sensitivity'
Hace referencia a la confidencialidad del mensaje. El parámetro es de tipo varchar(12). El parámetro puede contener uno de los siguientes valores:
- Normal
- Personal
- Private
- Confidential
El valor predeterminado es Normal.
[ @file_attachments= ] 'file_attachments'
Lista de nombres, separados por punto y coma, de los archivos que se van a adjuntar al mensaje de correo. 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.
[ @query= ] 'query'
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 de Transact-SQL válida. Tenga en cuenta que la consulta se ejecuta en una sesión independiente, por lo que las variables locales del script que llama a sp_send_dbmail no están disponibles para la consulta.
[ @execute_query_database= ] 'execute_query_database'
Contexto de base de datos dentro del cual el procedimiento almacenado ejecuta la consulta. El parámetro es de tipo sysname y su valor predeterminado es la base de datos actual. Este parámetro solo se puede aplicar 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 y su valor predeterminado es 0.

Si 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. Si el valor es 1, los resultados se devuelven como dato adjunto. Este parámetro solo se puede aplicar si se especifica @query.
[ @query_attachment_filename= ] 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) y su valor predeterminado es NULL. Este parámetro se omite cuando attach_query_result es 0. Cuando el valor de attach_query_result es 1 y el valor de este parámetro es NULL, el 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 de query_result_header es de tipo bit. Si el valor es 1, los resultados de la consulta contienen encabezados de columna. Si el valor es 0, los resultados de la consulta no contienen encabezados de columna. El valor predeterminado de este parámetro es 1. Este parámetro solo se puede aplicar si se especifica @query.
[ @query_result_width = ] query_result_width
Ancho de línea, en caracteres, que se utiliza para dar formato a los resultados de la consulta. query_result_width es de tipo int y su valor predeterminado es 256. El valor proporcionado debe estar entre 10 y 32767. Este parámetro solo se puede aplicar 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 de tipo bit y su valor predeterminado es 0. Si este parámetro es 0, la ejecución del procedimiento almacenado sp_send_dbmail imprime el mensaje devuelto como resultado de la ejecución de la consulta en la consola. Si este parámetro es 1, la ejecución del procedimiento almacenado sp_send_dbmail no muestra ningún mensaje de ejecución de la consulta en la consola.
[ @append_query_error= ] append_query_error
Especifica si se debe enviar el mensaje de correo electrónico cuando se devuelve un error desde la consulta especificada en el argumento @query. append_query_error es de tipo bit y su valor predeterminado es 0. Cuando este parámetro es 1, el Correo electrónico de base de datos envía el mensaje de correo electrónico e incluye en el cuerpo del mismo el mensaje de error de la consulta. Si el parámetro es 0, el Correo electrónico de base de datos no envía el mensaje de correo electrónico y sp_send_dbmail finaliza con un código de retorno 1, 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). Si el establece, los resultados de la consulta no contienen encabezados de columna. query_no_truncate es de tipo bit. Si el valor es 0 o no se especifica, las columnas de la consulta se truncan a 256 caracteres. Si el valor es 1, las columnas de la consulta no se truncan. El valor predeterminado de este parámetro es 0.

[!NOTA]

Si se utiliza con grandes cantidades de datos, la opción @query_no_truncate consume recursos adicionales y puede reducir 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, posiblemente, reducirá el tamaño del archivo. Si establece el parámetro @query\_result\_no\_padding en 1 y el parámetro @query\_result\_width, el parámetro @query\_result\_no\_padding no sobrescribe el parámetro @query\_result\_width.

En este caso no se producen errores.

Si establece el parámetro @query\_result\_no\_padding en 1 y el parámetro @query\_no\_truncate, se genera un error.
[ @mailitem_id= ] mailitem_id [ OUTPUT ]
El parámetro de salida opcional devuelve el valor de mailitem_id del mensaje. mailitem_id es de tipo int.

Valores de código de retorno

Un código de retorno de 0 significa éxito. Cualquier otro valor significa error. El código de error para la instrucción que dio lugar a error se almacena en la variable @ @ERRROR.

Conjuntos de resultados

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

Comentarios

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

sysmail_stop_sp detiene el Correo electrónico de base de datos al detener los objetos de Service Broker que utiliza el programa externo. sp_send_dbmail sigue aceptando correo aunque el Correo electrónico de base de datos se haya detenido mediante sysmail_stop_sp. Para iniciar el Correo electrónico de base de datos, utilice sysmail_start_sp.

Si no se especifica @profile, sp_send_dbmail utiliza 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 un perfil privado predeterminado, sp_send_dbmail utiliza el perfil público predeterminado. Si no hay ningún perfil privado predeterminado para el usuario ni tampoco 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 como mínimo uno de estos valores: @body, @query, @file_attachments o @subject. De lo contrario, sp_send_dbmail devuelve un error.

El Correo electrónico de base de datos utiliza el contexto de seguridad de Microsoft Windows del usuario actual para controlar el acceso a los archivos. Por lo tanto, los usuarios autenticados mediante autenticación de SQL Server no puede adjuntar archivos utilizando @file_attachments. Tenga en cuenta que Windows no permite que SQL Server proporcione credenciales desde un equipo remoto a otro. Por lo tanto, es posible que el Correo electrónico de base de datos no pueda adjuntar archivos desde un recurso compartido de red en aquellos casos en los que el comando se ejecuta desde un equipo que no sea el equipo donde se ejecuta SQL Server.

Si se especifican @query y @file_attachments y no se puede encontrar el archivo, la consulta se ejecuta pero no se envía el mensaje de 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 de direcciones de correo electrónico separadas por punto y coma. Debe especificarse como mínimo uno de estos parámetros; de lo contrario sp_send_dbmail devuelve un error.

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

Permisos

De forma predeterminada, pueden ejecutar sp_send_dbmail todos los miembros del rol de base de datos DatabaseMailUser de la base de datos msdb. No obstante, si el usuario que envía el mensaje no tiene permiso para utilizar 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 Dan Wilson utilizando la dirección de correo electrónico danw@Adventure-Works.com. 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 = 'danw@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 Dan Wilson utilizando la dirección de correo electrónico danw@Adventure-Works.com. El asunto del mensaje es Work Order Count, y ejecuta una consulta que muestra el número de órdenes de trabajo con un valor de DueDate inferior a dos días después del 30 de abril de 2004. 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 = '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.Enviar un mensaje de correo electrónico HTML

En este ejemplo se envía un mensaje de correo electrónico a Dan Wilson utilizando la dirección de correo electrónico danw@Adventure-Works.com. El asunto del mensaje es Work Order List y contiene un documento HTML que muestra las órdenes de trabajo con un valor de DueDate inferior a dos días después del 30 de abril de 2004. 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
              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' ;