xp_sendmail (Transact-SQL)

Syntaxe

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' ]

Arguments

• [ @recipients=] **'**recipients [ ;... n] '
  Liste des destinataires, délimitée par des points-virgules, auxquels le message électronique est envoyé.

• [ @message=] 'message'
  Corps du message à envoyer. L'argument messagepeut comporter jusqu'à 8 000 octets.

• [ @query=] 'query'
  Spécifie une requête SQL Server valide dont le résultat est envoyé dans le message électronique. xp_sendmail utilise une connexion liée pour le paramètre query. La connexion query établie par SQL Mail n'est pas bloquée par les verrous détenus par le client envoyant la demande xp_sendmail. L'utilisation de xp_sendmail est ainsi simplifiée à partir des déclencheurs. Toutefois, l'instruction query ne peut pas faire référence aux tables logiques inserted et deleted car elles sont disponibles uniquement dans un déclencheur. L'argument querypeut comporter jusqu'à 8 000 octets.

• [ @attachments=] **'**attachments [ ;... n] '
  Liste de fichiers à attacher au message électronique (délimitée par des points-virgules). Si vous utilisez le paramètre @query lorsque la valeur de @attach_results est TRUE, le paramètre @attachments ne peut spécifier qu'un seul fichier à joindre au message électronique. Si vous voulez envoyer plusieurs fichiers, exécutez xp_sendmail séparément pour chaque fichier joint.

• [ @copy_recipients=] **'**copy_recipients [ ;... n] '
  Liste des destinataires d'une copie du message électronique (délimitée par des points-virgules).

• [ @blind_copy_recipients=] **'**blind_copy_recipients[ ;... n] '
  Liste facultative des destinataires d'une copie invisible du message électronique (délimitée par des points-virgules).

• [ @subject=] 'subject'
  Paramètre spécifiant l'objet du message. Si subject est omis, « Message SQL Server » est la valeur par défaut.

• [ @type = ] 'type'
  Type de message d'entrée basé sur la définition de messagerie MAPI :

  IP[ M|C ].Vendorname.subclass

  Si l'argument type est NULL, xp_sendmail utilise un message de type IPM. Les types de messages commençant par IPM s'affichent dans la boîte de réception du client de messagerie et sont recherchés ou lus par xp_findnextmsg. Les types de messages commençant par IPC n'apparaissent pas dans la boîte de réception du client de messagerie et doivent être recherchés ou lus en définissant le paramètre type. La valeur par défaut est NULL. SQL Mail prend en charge les messages de type IPM et IPC.

• [ @attach_results=] 'attach_value'
  Paramètre facultatif qui spécifie que l'ensemble de résultats d'une requête doit être envoyé par messagerie électronique sous forme de fichier joint au lieu d'être ajouté au message. Si la valeur de @attachments n'est pas NULL et que celle de @attach_results est TRUE, c'est le premier nom de fichier dans attachments qui est utilisé comme nom de fichier pour les résultats. Si la valeur de @attachments est NULL, un nom de fichier est généré avec l'extension .txt. La valeur par défaut de ce paramètre est FALSE, ce qui signifie que l'ensemble de résultats est ajouté au message.

• [ @no_output=] 'output_value'
  Paramètre facultatif qui envoie le message électronique mais ne renvoie aucun état de sortie à la session client qui a émis le message. La valeur par défaut est FALSE, ce qui signifie que la session cliente de SQL Server reçoit un état de sortie.

• [ @no_header=] 'header_value'
  Paramètre facultatif qui envoie les résultats d'une requête dans le courrier mais n'envoie pas l'information des en-têtes de colonne avec ceux-ci. La valeur par défaut est FALSE, ce qui signifie que les en-têtes de colonne sont envoyés avec les résultats de la requête.

• [ @width=] width
  Paramètre facultatif qui définit la largeur des lignes du texte de sortie d'une requête. Ce paramètre est identique au paramètre /w dans l'utilitaire isql. Pour des requêtes produisant de longues lignes de sortie, utilisez width avecattach_results pour envoyer le résultat sans saut de ligne au milieu des lignes de sortie. La largeur par défaut est de 80 caractères.

• [ @separator=] 'separator'
  Caractères de séparation des colonnes pour chaque colonne de l'ensemble de résultats. Par défaut, le séparateur de colonnes est un espace. L'utilisation d'un séparateur de colonnes simplifie l'analyse de l'ensemble de résultats dans les tableurs et dans d'autres applications. Par exemple, vous utilisez separator avec attach_results pour envoyer des fichiers dont les données sont séparées par des virgules.

• [ @echo_error=] 'echo_value'
  TRUE provoque la capture par SQL Mail de toute erreur de la bibliothèque de bases de données ou de tout message du serveur rencontré durant l'exécution de la requête pour l'ajouter au message électronique au lieu de l'inscrire dans le journal des erreurs. Un décompte des lignes renvoyées/lignes affectées est également ajouté au message.

  Notes

  Si la valeur de echo_error est TRUE, xp_sendmail renvoie l’état 0 (succès) si le message électronique a été envoyé correctement, même si des erreurs ou des messages de la bibliothèque de bases de données sont rencontrés ou si la requête ne renvoie pas de résultat.

• [ @set_user=] 'user'
  Contexte de sécurité dans lequel la requête doit être exécutée. Si l'argument user n'est pas spécifié, le contexte de sécurité est par défaut celui de l'utilisateur qui exécute xp_sendmail.

• [ @dbuse=] 'database'
  Contexte de base de données dans lequel la requête doit être exécutée. La valeur par défaut est NULL, ce qui signifie que l'utilisateur est placé dans la base de données par défaut.

Valeurs du code de retour

0 (succès) ou 1 (échec)

Ensembles de résultats

En cas de réussite de l'opération, xp_sendmail renvoie un message.

Notes

La session SQL Mail doit être démarrée avant d'exécuter la procédure xp_sendmail. Les sessions peuvent être démarrées automatiquement ou à l'aide de xp_startmail. Pour plus d'informations sur la configuration automatique d'une session SQL Mail, consultez Configuration des profils de messagerie MAPI étendu. Une session SQL Mail prend en charge tous les utilisateurs pour l'instance SQL Server, mais seul un utilisateur à la fois peut envoyer un message. Les autres utilisateurs désireux d'envoyer automatiquement des messages électroniques doivent attendre que le message du premier utilisateur soit envoyé.

Si l'argument query est spécifié, xp_sendmail se connecte à SQL Server en tant que client et exécute la requête spécifiée. SQL Mail établit une connexion distincte à SQL Server ; ce composant ne partage pas la même connexion que la connexion cliente d'origine qui a lancé xp_sendmail.

xp_sendmail s'exécute dans le contexte de sécurité de SQL Server. Un utilisateur valide de la procédure xp_sendmail peut accéder à des fichiers pour les joindre à un message électronique dans le contexte de sécurité d'un administrateur. Si des utilisateurs autres que les administrateurs système doivent accéder à xp_sendmail et que vous voulez vous prémunir contre un accès non sécurisé aux fichiers joints, l'administrateur système peut créer une procédure stockée qui appelle xp_sendmail et fournit la fonctionnalité requise mais qui n'expose pas le paramètre attachments. Cette procédure stockée doit être définie dans la base de données master. L'administrateur système accorde ensuite aux utilisateurs qui en ont besoin l'autorisation d'exécution de la procédure stockée sans accorder d'autorisation sur la procédure xp_sendmail sous-jacente.

xp_sendmail envoie un message avec une pièce jointe ou un ensemble de résultats de la requête aux destinataires spécifiés et utilise une connexion liée pour le paramètre query. La connexion query établie par SQL Mail n'est pas bloquée par les verrous détenus par le client envoyant la requête xp_sendmail. L'utilisation de xp_sendmail est ainsi simplifiée à partir des déclencheurs. Toutefois, l'instruction query ne peut pas faire référence aux tables logiques insérées et supprimées qui sont disponibles uniquement dans un déclencheur.

La procédure xp_sendmail ne prend pas complètement en charge le type de données xml. La mise en forme des requêtes qui utilisent le type de données xml peut ne pas être correcte. Utilisez la Messagerie de base de données pour envoyer un courrier électronique comportant des données xml.

Autorisations

Nécessite l'appartenance au rôle de serveur fixe sysadmin, mais les autorisations EXECUTE peuvent être accordées à d'autres utilisateurs. Cependant, pour des raisons de sécurité, nous vous conseillons de limiter les autorisations pour cette procédure stockée aux membres du rôle de serveur fixe sysadmin.

Exemples

A. Envoi d'un message à un seul destinataire

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

B. Envoi d'un message à plusieurs destinataires

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. Envoi de résultats

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

D. Envoi de résultats sous forme de fichier joint

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. Envoi de messages comportant plus de 7 990 caractères (octets)

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 ;

Voir aussi

Référence