xp_sendmail (Transact-SQL)
Envoie aux destinataires spécifiés un message électronique pouvant comporter en pièce jointe l'ensemble de résultats d'une requête. Cette procédure stockée étendue utilise SQL Mail pour envoyer le message.
[!REMARQUE]
Cette fonctionnalité sera supprimée dans une prochaine version de Microsoft SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité. Pour envoyer du courrier à partir de SQL Server, utilisez la Messagerie de base de données.
.gif "Icône Lien de rubrique")
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.[!REMARQUE]
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.
[!REMARQUE]
L'argument query peut être bloqué par un verrou détenu par la connexion cliente qui a lancé xp_sendmail. Par exemple, si vous effectuez la mise à jour d'une table au sein d'une transaction et que, pour cette mise à jour, vous créez un déclencheur qui tente de sélectionner les mêmes informations de ligne mises à jour que le paramètre query, la connexion SQL Mail est bloquée par le verrou exclusif détenu sur cette ligne par la connexion cliente initiale.
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.
[!REMARQUE]
Une violation d'accès peut survenir à la suite d'une tentative d'exécution de la procédure xp_sendmail lorsque le bureau de poste et le carnet d'adresses se trouvent sur un partage de fichiers auquel le service MSSQLServer ne peut accéder en raison d'autorisations inappropriées.
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
Dans l'exemple suivant, un message est envoyé à l'utilisateur Dan Wilson (adresse de messagerie : danw) pour lui signaler que la base de données master est saturée.
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
Dans l'exemple suivant, le message est envoyé aux utilisateurs Dan Wilson et Ashvini Sharma (adresse de messagerie : ashvinis), tandis qu'une copie est envoyée à Peter Connelly (adresse de messagerie : peterc). Cet exemple spécifie également une ligne d'objet pour le message.
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
L'exemple suivant envoie les résultats de la procédure stockée sp_configure à Dan Wilson.
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
L'exemple suivant envoie les résultats de la requête SELECT * FROM INFORMATION_SCHEMA.TABLES à Dan Wilson dans un fichier texte joint. Cet exemple inclut une ligne d'objet et un message qui sera inséré avant la pièce jointe. Le paramètre @width est utilisé pour éviter les sauts de ligne dans les lignes de sortie.
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)
L'exemple suivant montre comment envoyer un message comportant plus de 7 990 caractères (octets). Étant donné que le paramètre message est limité à la longueur du type VARCHAR (moins de surcharge de ligne, comme tous les paramètres des procédures stockées), cet exemple écrit le message long dans une table temporaire globale qui est constituée d'une colonne de texte unique. Le contenu de cette table temporaire est ensuite envoyé dans le message au moyen du paramètre @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 ;