sp_send_dbmail (Transact-SQL)

Artículo
12/15/2008

Actualizado: 5 de diciembre de 2005

Envía un mensaje de correo electrónico a los destinatarios especificados. El mensaje puede incluir un conjunto de resultados de una consulta, archivos 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 ]' ]
    [ , [ @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.

[ @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 archivos adjuntos es de tipo nvarchar(max).

[ @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 de la secuencia de comandos 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 sólo 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 archivo 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 archivo adjunto. Este parámetro sólo 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 el valor de attach_query_result es 0. Si el valor de attach_query_result es 1 y 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 sólo 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 sólo se aplica 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 muestra 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 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 de datos es bit. El valor predeterminado es 0. Cuando se establece en 1, no se rellenan los resultados de la consulta, lo que posiblemente reduce el tamaño de archivo.

Si establece @query\_result\_no\_padding en 1 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 genera ningún error.

Si establece @query\_result\_no\_padding en 1 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 valor de mailitem_id del mensaje. mailitem_id es de tipo int.

Conjuntos de resultados

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

Notas

Antes de utilizar el Correo electrónico de base de datos, debe habilitarlo con el Asistente para configuración de Correo electrónico de base de datos, la herramienta de configuración de superficie de SQL Server 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 en línea. 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 de la función 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.

Valores de código de retorno

0 (correcto) o 1 (error)

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 = 'AdventureWorks 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 = 'AdventureWorks Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks.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' ;

Vea también

Historial de cambios

Versión	Historial
5 de diciembre de 2005	Contenido nuevo: Se ha descrito el comportamiento de la transacción de sp_send_dbmail.

Compartir a través de