xp_sendmail (Transact-SQL)

Envía un mensaje de correo electrónico, que puede incluir un conjunto de resultados de una consulta como datos adjuntos, a los destinatarios especificados. Este procedimiento almacenado ampliado utiliza SQL Mail para enviar el mensaje.

[!NOTA] Esta característica se quitará en una versión futura de Microsoft SQL Server. Evite utilizar esta característica en nuevos trabajos de desarrollo y tenga previsto modificar las aplicaciones que actualmente la utilizan. Para enviar correo desde SQL Server, utilice Correo electrónico de base de datos.

Convenciones de sintaxis de Transact-SQL

Sintaxis

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] '
  Es la lista, separada por puntos y comas, de los destinatarios del mensaje de correo.

• [ @message=] 'message'
  Es el cuerpo del mensaje que se va a enviar. messagepuede tener hasta 8.000 bytes.

• [ @query=] 'query'
  Es una consulta de SQL Server válida, cuyo resultado se envía en un mensaje de correo electrónico. xp_sendmail utiliza una conexión enlazada para el parámetro query. La conexión query realizada por SQL Mail no está bloqueada por los bloqueos que mantiene el cliente que emite la solicitud xp_sendmail. Esto hace que xp_sendmail sea más fácil de utilizar en desencadenadores. Sin embargo, la instrucción query no puede hacer referencia a las tablas lógicas insertadas y eliminadas, ya que estas tablas sólo están disponibles con un desencadenador. querypuede tener hasta 8.000 bytes.

• [ @attachments=] **'**attachments [ ;... n] '
  Es una lista de archivos separados por punto y coma para adjuntarlos al mensaje de correo. Si utiliza el parámetro @query cuando @attach_results es TRUE, el parámetro @attachments sólo puede especificar un archivo para adjuntarlo al mensaje de correo electrónico. Para enviar más de un archivo, debe ejecutar xp_sendmail por separado para cada archivo adjunto.

• [ @copy_recipients=] **'**copy_recipients [ ;... n] '
  Es la lista, separada por puntos y comas, que identifica a los destinatarios de copias del mensaje de correo.

• [ @blind_copy_recipients=] **'**blind_copy_recipients[ ;... n] '
  Es una lista opcional, separada por puntos y comas, que identifica a los destinatarios de copias ocultas del mensaje de correo.

• [ @subject=] 'subject'
  Es un parámetro que especifica el asunto del mensaje. Si subjectno se ha especificado, el valor predeterminado es "Mensaje de SQL Server".

• [ @type=] 'type'
  Es el tipo de mensaje de entrada basado en la definición de correo MAPI:

  IP[ M|C ].Vendorname.subclass

  Si type es NULL, xp_sendmail utiliza un mensaje de tipo IPM. Los tipos de mensajes que empiezan por IPM aparecen en la bandeja de entrada del cliente de correo y se buscan y leen mediante xp_findnextmsg. Los tipos de mensajes que empiezan por IPC no aparecen en la bandeja de entrada del cliente de correo y se tienen que buscar o leer estableciendo el parámetro type. El valor predeterminado es NULL. SQL Mail admite los tipos de mensajes IPM e IPC.

• [ @attach_results=] 'attach_value'
  Es un parámetro opcional que especifica si el conjunto de resultados de una consulta se envía como archivo adjunto en el mensaje, en lugar de en el propio mensaje. Si @attachments no es NULL y @attach_results es TRUE, el primer nombre de archivo de attachments se utiliza como nombre de archivo de los resultados. Si @attachments es NULL, se genera un nombre de archivo con la extensión .txt. El valor predeterminado es FALSE, que significa que el conjunto de resultados se incluye en el mensaje.

• [ @no_output=] 'output_value'
  Es un parámetro opcional que envía el mensaje pero no devuelve ninguna salida a la sesión del cliente que lo envía. El valor predeterminado es FALSE, lo que significa que la sesión del cliente de SQL Server recibe su salida.

• [ @no_header=] 'header_value'
  Es un parámetro opcional que envía los resultados de la consulta en el mensaje, pero no envía información de los encabezados de las columnas junto con los resultados de la consulta. El valor predeterminado es FALSE, que significa se envía información de los encabezados de las columnas junto con los resultados de la consulta.

• [ @width=] width
  Es un parámetro opcional que establece el ancho de la línea del texto de salida de la consulta. Este parámetro es idéntico al parámetro /w de la utilidad isql. Para consultas que producen filas de salida largas, use width con attach_results para enviar la salida sin saltos de línea entre las líneas de salida. El ancho predeterminado es 80 caracteres.

• [ @separator=] 'separator'
  Es la cadena de separador de columna para cada columna del conjunto de resultados. De manera predeterminada, el separador de columna es un espacio en blanco. El uso de un separador de columna facilita el análisis del conjunto de resultados en hojas de cálculo y otras aplicaciones. Por ejemplo, use separator con attach_results para enviar archivos con valores separados por comas.

• [ @echo_error=] 'echo_value'
  Cuando es TRUE, hace que SQL Mail capture los mensajes del servidor o los errores de DB-Library encontrados al ejecutar la consulta, y que los adjunte al mensaje de correo en lugar de escribirlos en el registro de errores. Asimismo, se adjunta al mensaje el recuento de las filas devueltas o afectadas.

  [!NOTA] Si echo_error es TRUE, xp_sendmail devuelve el estado 0 (correcto) en caso de que el mensaje se envíe correctamente, incluso si se encuentran errores o mensajes de DB-Library, o si la consulta no devuelve resultados.

• [ @set_user=] 'user'
  Es el contexto de seguridad en el que se debe ejecutar la consulta. Si user no se ha especificado, el contexto de seguridad predeterminado adopta el valor del usuario que ejecuta xp_sendmail.

• [ @dbuse=] 'database'
  Es el contexto de la base de datos en la que se tiene que ejecutar la consulta. El valor predeterminado es NULL, que significa que el usuario se encuentra en la base de datos predeterminada.

Conjuntos de resultados

Cuando es correcto, xp_sendmail devuelve un mensaje.

Notas

La sesión de SQL Mail debe iniciarse antes de ejecutar xp_sendmail. Las sesiones se pueden iniciar automáticamente o con xp_startmail. Para obtener más información acerca de cómo configurar una sesión de SQL Mail automáticamente, vea Configurar perfiles de correo de la MAPI extendida. Una sesión de SQL Mail admite todos los usuarios de la instancia de SQL Server, pero sólo un usuario a la vez puede enviar un mensaje. El resto de los usuarios que envíen mensajes esperan su turno automáticamente hasta que se envíen los mensajes anteriores a los suyos.

Si se especifica query, xp_sendmail inicia una sesión como cliente en SQL Server y ejecuta la consulta especificada. SQL Mail establece una conexión diferente con SQL Server; no comparte la misma conexión que la conexión de cliente original que ejecuta xp_sendmail.

[!NOTA] El parámetro query puede estar bloqueado por bloqueos mantenidos por la conexión del cliente que ejecuta xp_sendmail. Por ejemplo, si está actualizando una tabla dentro de una transacción y crea un desencadenador para la actualización que intenta seleccionar la misma información de fila actualizada como parámetro query, la conexión de SQL Mail queda bloqueada por el bloqueo exclusivo mantenido sobre la fila por la conexión inicial del cliente.

xp_sendmail se ejecuta en el contexto de seguridad de SQL Server. Un usuario válido de xp_sendmail puede tener acceso a archivos para adjuntarlos al mensaje dentro del contexto de seguridad del administrador. Si otros usuarios que no sean administradores del sistema deben obtener acceso a xp_sendmail y desea protección frente a cualquier acceso no seguro a archivos adjuntos, el administrador del sistema puede crear un procedimiento almacenado que llame a xp_sendmail y proporcione la funcionalidad necesaria, pero que no exponga el parámetro attachments. Dicho procedimiento almacenado tiene que estar definido en la base de datos master. A continuación, el administrador del sistema concede permisos de ejecución sobre este procedimiento almacenado a los usuarios necesarios sin tener que conceder permisos sobre el propio procedimiento xp_sendmail.

xp_sendmail envía un mensaje y el conjunto de resultados de una consulta o un adjunto a los destinatarios especificados, y utiliza una conexión enlazada en el parámetro query. La conexión query realizada por SQL Mail no está bloqueada por los bloqueos que mantiene el cliente que emite la solicitud xp_sendmail. Esto hace que xp_sendmail sea más fácil de utilizar en desencadenadores. Sin embargo, la instrucción query no puede hacer referencia a las tablas lógicas insertadas y eliminadas que sólo están disponibles dentro de los desencadenadores.

[!NOTA] Se puede producir una infracción de acceso al intentar ejecutar xp_sendmail cuando la oficina de correo y la libreta de direcciones se encuentran en un recurso compartido de archivos al que el servicio MSSQLServer no puede obtener acceso porque no tiene los permisos adecuados.

xp_sendmail no es totalmente compatible con el tipo de datos xml incluido en SQL Server 2005. Las consultas que utilizan el tipo de datos xml pueden tener un formato incorrecto. Utilice Correo electrónico de base de datos para enviar un correo electrónico que incluya datos xml.

Permisos

Debe pertenecer a la función fija de servidor sysadmin, pero se pueden conceder permisos EXECUTE a otros usuarios. Sin embargo, por razones de seguridad, se recomienda limitar los permisos para este procedimiento almacenado a los miembros de la función fija de servidor sysadmin.

Valores de código de retorno

0 (correcto) o 1 (error)

Ejemplos

A. Enviar un mensaje a un destinatario individual

En el ejemplo siguiente se envía un mensaje al usuario Dan Wilson (cuya dirección de correo electrónico es danw) para comunicarle que la base de datos master está llena.

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @message=N'The master database is full.' ;

B. Enviar un mensaje a varios destinatarios

En el ejemplo siguiente se envía el mensaje a los usuarios Dan Wilson y Ashvini Sharma (cuya dirección de correo electrónico es ashvinis), y también se envía una copia a Peter Connelly (cuya dirección de correo electrónico es peterc). También se especifica la línea del asunto del mensaje.

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. Enviar resultados

En el ejemplo siguiente se envían los 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. Enviar resultados como archivo adjunto

En el ejemplo siguiente se envían a Dan Wilson los resultados de la consulta SELECT * FROM INFORMATION_SCHEMA.TABLES como archivo de texto adjunto. Se incluye la línea del asunto del mensaje y un mensaje que aparece antes del adjunto. El parámetro @width se utiliza para impedir saltos de línea en la salida.

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. Enviar mensajes de más de 7.990 caracteres de byte

En el ejemplo siguiente se muestra cómo enviar un mensaje de más de 7.990 caracteres de byte. Como la longitud de message está limitada a la longitud de una variable VARCHAR (menos recursos para la fila, como todos los parámetros de los procedimientos almacenados), este ejemplo escribe el mensaje largo en una tabla temporal global que se compone de una columna de texto. El contenido de dicha tabla temporal se envía en el mensaje mediante el 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 ;

Vea también

Referencia

sp_processmail (Transact-SQL)
Procedimientos almacenados del sistema (Transact-SQL)
xp_deletemail (Transact-SQL)
xp_findnextmsg (Transact-SQL)
xp_readmail (Transact-SQL)
xp_startmail (Transact-SQL)
xp_stopmail (Transact-SQL)
sp_send_dbmail (Transact-SQL)

Ayuda e información

Obtener ayuda sobre SQL Server 2005