sp_send_dbmail (Transact-SQL)

Sendet eine E-Mail-Nachricht an die angegebenen Empfänger. Die Nachricht kann ein Abfrageresultset, Dateianlagen oder beides enthalten. Wenn Nachrichten erfolgreich in die Datenbank-E-Mail-Warteschlange platziert werden, gibt sp_send_dbmail den Wert für mailitem_id der Nachricht zurück. Diese gespeicherte Prozedur wird in der msdb-Datenbank gespeichert.

Transact-SQL-Syntaxkonventionen

Syntax

sp_send_dbmail [ [ @profile_name = ] 'profile_name' ]
    [ , [ @recipients = ] 'recipients [ ; ...n ]' ]
    [ , [ @copy_recipients = ] 'copy_recipient [ ; ...n ]' ]
    [ , [ @blind_copy_recipients = ] 'blind_copy_recipient [ ; ...n ]' ]
    [ , [ @from_address = ] 'from_address' ]
    [ , [ @reply_to = ] 'reply_to' ] 
    [ , [ @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 ]

Argumente

• [ @profile_name= ] 'profile_name'
  Der Name des Profils, von dem die Nachricht gesendet werden soll. profile_name ist vom Datentyp sysname; der Standardwert ist NULL. profile_name muss der Name eines vorhandenen Datenbank-E-Mail-Profils sein. Wenn profile_name nicht angegeben ist, verwendet sp_send_dbmail das private Standardprofil für den aktuellen Benutzer. Verfügt der Benutzer nicht über ein privates Standardprofil, verwendet sp_send_dbmail das öffentliche Standardprofil für die msdb-Datenbank. Verfügt der Benutzer nicht über ein privates Standardprofil und es ist kein öffentliches Standardprofil für die Datenbank vorhanden, muss @profile_name angegeben sein.

• [ @recipients= ] 'recipients'
  Eine durch Semikolons getrennte Liste der E-Mail-Adressen, an die die Nachricht gesendet werden soll. Die Empfängerliste ist vom Typ varchar(max). Obwohl dieser Parameter optional ist, muss mindestens einer der Werte für @recipients, @copy_recipients oder @blind_copy_recipients angegeben sein. Andernfalls gibt sp_send_dbmail einen Fehler zurück.

• [ @copy_recipients= ] 'copy_recipients'
  Eine durch Semikolons getrennte Liste der E-Mail-Adressen, an die eine Kopie der Nachricht gesendet werden soll. Die Liste der Kopieempfänger ist vom Typ varchar(max). Obwohl dieser Parameter optional ist, muss mindestens einer der Werte für @recipients, @copy_recipients oder @blind_copy_recipients angegeben sein. Andernfalls gibt sp_send_dbmail einen Fehler zurück.

• [ @blind_copy_recipients= ] 'blind_copy_recipients'
  Eine durch Semikolons getrennte Liste der E-Mail-Adressen, an die eine Kopie der Nachricht als BCC-Empfänger gesendet werden soll. Die Liste der BCC-Empfänger ist vom Typ varchar(max). Obwohl dieser Parameter optional ist, muss mindestens einer der Werte @recipients, @copy_recipients oder @blind_copy_recipients angegeben werden. Andernfalls gibt sp_send_dbmail einen Fehler zurück.

• [ @from_address= ] 'from_address'
  Der Wert der Absenderadresse der E-Mail-Nachricht. Dies ist ein optionaler Parameter, mit dem die Einstellungen im Mailprofil überschrieben werden. Der Parameter ist vom Datentyp varchar(MAX). SMTP-Sicherheitseinstellungen stellen fest, ob diese Überschreibungen akzeptiert werden. Wenn kein Parameter angegeben ist, wird der Standardwert NULL verwendet.

• [ @reply_to= ] 'reply_to'
  Der Wert der Antwortadresse der E-Mail-Nachricht. Er akzeptiert nur eine E-Mail-Adresse als gültigen Wert. Dies ist ein optionaler Parameter, mit dem die Einstellungen im Mailprofil überschrieben werden. Der Parameter ist vom Datentyp varchar(MAX). SMTP-Sicherheitseinstellungen stellen fest, ob diese Überschreibungen akzeptiert werden. Wenn kein Parameter angegeben ist, wird der Standardwert NULL verwendet.

• [ @subject= ] 'subject'
  Der Betreff der E-Mail-Nachricht. Der Betreff ist vom Datentyp nvarchar(255). Wenn Sie keinen Betreff angeben, wird standardmäßig 'SQL Server-Nachricht' verwendet.

• [ @body= ] 'body'
  Der Text der E-Mail-Nachricht. Der Nachrichtentext ist vom Datentyp nvarchar(max) und hat den Standardwert NULL.

• [ @body_format= ] 'body_format'
  Das Format des Nachrichtentexts. Der Parameter ist vom Datentyp varchar(20) und hat den Standardwert NULL. Wenn der Parameter angegeben ist, wird in den Headern der ausgehenden Nachricht angezeigt, dass der Nachrichtentext das angegebene Format besitzt. Der Parameter kann einen der folgenden Werte enthalten:

  • TEXT

  • HTML

  Der Standardwert ist TEXT.

• [ @importance= ] 'importance'
  Die Bedeutung der Nachricht. Der Parameter ist vom Datentyp varchar(6). Der Parameter kann einen der folgenden Werte enthalten:

  • Niedrig

  • Normal

  • Hoch

  Der Standardwert ist Normal.

• [ @sensitivity= ] 'sensitivity'
  Die Vertraulichkeit der Nachricht. Der Parameter ist vom Datentyp varchar(12). Der Parameter kann einen der folgenden Werte enthalten:

  • Normal

  • Persönlich

  • Privat

  • Vertraulich

  Der Standardwert ist Normal.

• [ @file_attachments= ] 'file_attachments'
  Die durch Semikolons getrennte Liste der Dateinamen, die an die E-Mail-Nachricht angehängt werden sollen. Die Dateien in der Liste müssen als absolute Pfade angegeben sein. Die Anlagenliste ist vom Typ nvarchar(max). Standardmäßig beschränkt Datenbank-E-Mail Dateianlagen auf 1 MB pro Datei.

• [ @query= ] 'query'
  Eine auszuführende Abfrage. Die Ergebnisse der Abfrage können als Datei angefügt oder in den Text der E-Mail-Nachricht eingeschlossen werden. Die Abfrage ist vom Datentyp nvarchar(max) und kann beliebige gültige Transact-SQL-Anweisungen enthalten. Beachten Sie, dass die Abfrage in einer separaten Sitzung ausgeführt wird, daher stehen der Abfrage lokale Variablen in dem Skript, das sp_send_dbmail aufruft, nicht zur Verfügung.

• [ @execute_query_database= ] 'execute_query_database'
  Der Datenbankkontext, in dem die gespeicherte Prozedur die Abfrage ausführt. Der Parameter ist vom Datentyp sysname. Standardwert ist die aktuelle Datenbank. Dieser Parameter ist nur verfügbar, wenn @query angegeben ist.

• [ @attach_query_result_as_file= ] attach_query_result_as_file
  Gibt an, ob das Resultset der Abfrage als Anlage zurückgegeben wird. attach_query_result_as_file ist vom Datentyp bit. Der Standardwert ist 0.

  Ist der Wert 0, werden die Abfrageergebnisse hinter dem Inhalt des @body-Parameters in den Text der E-Mail-Nachricht eingeschlossen. Ist der Wert 1, werden die Ergebnisse als Anlage zurückgegeben. Dieser Parameter ist nur verfügbar, wenn @query angegeben ist.

• [ @query_attachment_filename= ] query_attachment_filename
  Gibt an, welcher Dateiname für das Resultset der Abfrageanlage verwendet wird. query_attachment_filename ist vom Datentyp nvarchar(255) und hat den Standardwert NULL. Dieser Parameter wird ignoriert, wenn attach_query_result 0 ist. Weist attach_query_result den Wert 1 und dieser Parameter den Wert NULL auf, erstellt Datenbank-E-Mail einen beliebigen Dateinamen.

• [ @query_result_header= ] query_result_header
  Gibt an, ob die Abfrageergebnisse Spaltenheader einschließen. Der Wert für query_result_header ist vom Datentyp bit. Bei einem Wert von 1 enthalten die Abfrageergebnisse Spaltenheader. Bei einem Wert von 0 enthalten die Abfrageergebnisse keine Spaltenheader. Dieser Parameter hat den Standardwert 1. Dieser Parameter ist nur verfügbar, wenn @query angegeben ist.

• [ @query_result_width = ] query_result_width
  Die Linienstärke in Zeichen, die zum Formatieren der Ergebnisse der Abfrage verwendet wird. query_result_width ist vom Typ int mit dem Standardwert 256. Der Wert muss zwischen 10 and 32767 liegen. Dieser Parameter ist nur verfügbar, wenn @query angegeben ist.

• [ @query_result_separator= ] 'query_result_separator'
  Das Zeichen, das zum Trennen der Spalten in der Abfrageausgabe verwendet wird. Das Trennzeichen ist vom Datentyp char(1). Der Standardwert ist ' ' (Leerzeichen).

• [ @exclude_query_output= ] exclude_query_output
  Gibt an, ob die Ausgabe der Abfrageausführung in der E-Mail-Nachricht zurückgegeben werden soll. exclude_query_output ist vom Datentyp bit. Der Standardwert ist 0. Wenn dieser Parameter gleich 0 ist, gibt die gespeicherte Prozedur sp_send_dbmail die zurückgegebene Nachricht als Ergebnis der Abfrageausführung auf der Konsole aus. Wenn dieser Parameter gleich 1 ist, gibt die gespeicherte Prozedur sp_send_dbmail keine Abfrageausführungsnachrichten auf der Konsole aus.

• [ @append_query_error= ] append_query_error
  Gibt an, ob die E-Mail-Nachricht gesendet wird, wenn ein Fehler aus der im @query-Argument angegebenen Abfrage zurückgegeben wird. append_query_error ist vom Datentyp bit. Der Standardwert ist 0. Ist dieser Parameter auf 1 festgelegt, sendet Datenbank-E-Mail die E-Mail-Nachricht und bezieht die Abfragefehlermeldung in den Text der E-Mail-Nachricht ein. Ist dieser Parameter auf 0 festgelegt, sendet Datenbank-E-Mail die E-Mail-Nachricht nicht, und sp_send_dbmail wird mit dem Rückgabecode 1 beendet, der einen Fehler anzeigt.

• [ @query_no_truncate= ] query_no_truncate
  Gibt an, ob die Abfrage mit der Option ausgeführt werden soll, die das Abschneiden von Datentypen variabler Länge, die für umfangreiche Daten verwendet werden (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image sowie benutzerdefinierte Datentypen), verhindern. Wenn fetgelegt, enthalten die Abfrageergebnisse keine Spaltenheader. query_no_truncate ist vom Datentyp bit. Bei einem Wert von 0 oder wenn kein Wert angegeben ist, werden die Spalten in der Abfrage auf 256 Zeichen abgeschnitten. Bei einem Wert von 1 werden die Spalten in der Abfrage nicht abgeschnitten. Dieser Parameter hat den Standardwert 0.

  Hinweis
  Wenn sie mit großen Datenmengen verwendet wird, nimmt die Option @query_no_truncate zusätzliche Ressourcen in Anspruch und verringert möglicherweise die Serverleistung.

• [ @query_result_no_padding ] @query\_result\_no\_padding
  Der Typ ist Bit. Der Standardwert ist 0. Wenn Sie ihn auf 1 festlegen, werden die Abfrageergebnisse nicht aufgefüllt und die Dateigröße u. U. reduziert. Wenn @query_result_no_padding auf 1 und gleichzeitig den @query_result_width-Parameter festlegen, überschreibt der @query_result_no_padding-Parameter den @query_result_width-Parameter.

  In diesem Fall tritt kein Fehler auf.

  Wenn Sie @query_result_no_padding auf 1 festlegen und den @query_no_truncate-Parameter ebenfalls festlegen, wird ein Fehler ausgelöst.

• [ @mailitem_id= ] mailitem_id [ OUTPUT ]
  Optionaler Ausgabeparameter, der den Wert mailitem_id der Nachricht zurückgibt. mailitem_id ist ein int-Typ.

Rückgabecodewerte

Ein Rückgabecode von 0 steht für Erfolg. Ein beliebiger anderer Wert steht für Fehler. Der Fehlercode für die fehlgeschlagene Anweisung wird in der @@ERRROR-Variablen gespeichert.

Resultsets

Bei Erfolg wird die Nachricht "E-Mail in der Warteschlange" zurückgegeben.

Hinweise

Vor der Verwendung muss Datenbank-E-Mail mit dem Assistenten zum Konfigurieren von Datenbank-E-Mail oder sp_configure aktiviert werden.

sysmail_stop_sp beendet Datenbank-E-Mail durch das Beenden der vom externen Programm verwendeten Service Broker-Objekte. sp_send_dbmail nimmt E-Mail weiterhin an, auch wenn Datenbank-E-Mail mithilfe von sysmail_stop_sp beendet wurde. Starten Sie Datenbank-E-Mail mithilfe von sysmail_start_sp.

Wenn @profile nicht angegeben ist, verwendet sp_send_dbmail ein Standardprofil. Falls der Benutzer, der die E-Mail-Nachricht sendet, über ein privates Standardprofil verfügt, verwendet Datenbank-E-Mail dieses Profil. Verfügt der Benutzer nicht über ein privates Standardprofil, verwendet sp_send_dbmail das öffentliche Standardprofil. Falls weder ein privates Standardprofil für den Benutzer noch ein öffentliches Standardprofil vorhanden ist, gibt sp_send_dbmail einen Fehler zurück.

E-Mail-Nachrichten ohne Inhalt werden von sp_send_dbmail nicht unterstützt. Wenn Sie eine E-Mail-Nachricht senden möchten, müssen Sie mindestens einen Wert für @body, @query, @file_attachments oder @subject angeben. Andernfalls gibt sp_send_dbmail einen Fehler zurück.

Datenbank-E-Mail verwendet den Microsoft Windows-Sicherheitskontext des aktuellen Benutzers, um den Dateizugriff zu steuern. Daher können Benutzer, die über die SQL Server-Authentifizierung angemeldet sind, mit @file_attachments keine Dateien anfügen. Windows lässt nicht zu, dass SQL Server Anmeldeinformationen von einem Remotecomputer für einen anderen Remotecomputer bereitstellt. Aus diesem Grund kann Datenbank-E-Mail möglicherweise Dateien aus einer Netzwerkfreigabe nicht anfügen, wenn der Befehl von einem anderen Computer als dem Computer mit SQL Server ausgeführt wird.

Wenn sowohl @query als auch @file_attachments angegeben sind und die Datei nicht gefunden wird, wird die Abfrage weiterhin ausgeführt, die E-Mail-Nachricht wird jedoch nicht gesendet.

Wird eine Abfrage angegeben, wird das Resultset als Inlinetext formatiert. Binärdaten im Ergebnis werden im hexadezimalen Format gesendet.

Die Parameter @recipients, @copy_recipients und @blind_copy_recipients sind durch Semikolons getrennte Listen mit E-Mail-Adressen. Mindestens einer dieser Parameter muss angegeben werden. Andernfalls gibt sp_send_dbmail einen Fehler zurück.

Wird sp_send_dbmail ohne Transaktionskontext ausgeführt, startet Datenbank-E-Mail eine implizite Transaktion und führt einen Commit für die Transaktion aus. Wird sp_send_dbmail innerhalb einer vorhandenen Transaktion ausgeführt, überlässt Datenbank-E-Mail es dem Benutzer, entweder einen Commit oder ein Rollback für Änderungen auszuführen. Es wird keine innere Transaktion gestartet.

Berechtigungen

Ausführungsberechtigungen für sp_send_dbmail werden standardmäßig allen Mitgliedern der DatabaseMailUser-Datenbankrolle in der msdb-Datenbank erteilt. Wenn der Benutzer, der die Nachricht sendet, jedoch nicht über die Berechtigung zum Verwenden des Profils für die Anforderung verfügt, gibt sp_send_dbmail einen Fehler zurück, und die Nachricht wird nicht gesendet.

Beispiele

A.Senden einer E-Mail-Nachricht

In diesem Beispiel wird eine E-Mail-Nachricht an Dan Wilson mit der E-Mail-Adresse danw@Adventure-Works.com gesendet. Die Nachricht hat den Betreff Automated Success Message. Der Nachrichtentext enthält den Satz 'The stored procedure finished successfully'.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @body = 'The stored procedure finished successfully.',
    @subject = 'Automated Success Message' ;

B.Senden einer E-Mail-Nachricht mit den Ergebnissen einer Abfrage

In diesem Beispiel wird eine E-Mail-Nachricht an Dan Wilson mit der E-Mail-Adresse danw@Adventure-Works.com gesendet. Die Nachricht hat den Betreff Work Order Count und führt eine Abfrage aus, die die Anzahl von Arbeitsaufträgen mit einem DueDate-Wert kleiner als zwei Tage nach dem 30. April 2004 anzeigt. Das Ergebnis wird als Textdatei von Datenbank-E-Mail angefügt.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2012.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.Senden einer E-Mail-Nachricht im HTML-Format

In diesem Beispiel wird eine E-Mail-Nachricht an Dan Wilson mit der E-Mail-Adresse danw@Adventure-Works.com gesendet. Die Nachricht hat den Betreff Work Order List und enthält ein HTML-Dokument, das die Anzahl von Arbeitsaufträgen mit einem DueDate-Wert kleiner als zwei Tage nach dem 30. April 2004 anzeigt. Das Ergebnis wird im HTML-Format von Datenbank-E-Mail gesendet.

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

Siehe auch

Verweis

Gespeicherte Prozeduren für Datenbank-E-Mail (Transact-SQL)

sp_addrolemember (Transact-SQL)

Konzepte

Datenbank-E-Mail

Konfigurationsobjekte für Datenbank-E-Mail