xp_sendmail (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.

Valores de código de retorno

0 (correcto) o 1 (error)

Conjuntos de resultados

Cuando es correcto, xp_sendmail devuelve un mensaje.

Comentarios

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.

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 maestra. 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.

xp_sendmail no es totalmente compatible con el tipo de datos xml.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.

Ejemplos

A. Enviar un mensaje a un destinatario individual

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

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

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @query = N'EXEC sp_configure' ;
GO

D. Enviar resultados como archivo adjunto

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

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