sp_send_dbmail (Transact-SQL)

gäller för:SQL ServerAzure SQL Managed Instance

Skickar ett e-postmeddelande till de angivna mottagarna. Meddelandet kan innehålla en frågeresultatuppsättning, bifogade filer eller båda. När e-post har placerats i Databasens e-postkö sp_send_dbmail returnerar mailitem_id meddelandet. Den här lagrade proceduren finns i msdb databasen.

Transact-SQL syntaxkonventioner

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 = ] N'subject' ]
    [ , [ @body = ] N'body' ]
    [ , [ @body_format = ] 'body_format' ]
    [ , [ @importance = ] 'importance' ]
    [ , [ @sensitivity = ] 'sensitivity' ]
    [ , [ @file_attachments = ] N'attachment [ ; ...n ]' ]
    [ , [ @query = ] N'query' ]
    [ , [ @execute_query_database = ] 'execute_query_database' ]
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]
    [ , [ @query_attachment_filename = ] N'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 ]
[ ; ]

Arguments

[ @profile_name = ] "profile_name"

Namnet på profilen som meddelandet ska skickas från. @profile_name är av typen sysname, med standardvärdet NULL. @profile_name måste vara namnet på en befintlig Database Mail-profil. När ingen @profile_name har angetts sp_send_dbmail använder den aktuella användarens privata standardprofil. Om användaren inte har någon privat standardprofil sp_send_dbmail använder den offentliga standardprofilen msdb för databasen. Om användaren inte har någon privat standardprofil och det inte finns någon offentlig standardprofil för databasen måste @profile_name anges.

[ @recipients = ] "mottagare"

En semikolonavgränsad lista över e-postadresser som meddelandet ska skickas till. Mottagarlistan är av typen varchar(max). Även om den här parametern är valfri måste minst en av @recipients, @copy_recipients eller @blind_copy_recipients anges eller sp_send_dbmail returnerar ett fel.

[ @copy_recipients = ] "copy_recipients"

En semikolonavgränsad lista över e-postadresser att kopiera meddelandet till. Listan med kopieringsmottagare är av typen varchar(max). Även om den här parametern är valfri måste minst en av @recipients, @copy_recipients eller @blind_copy_recipients anges eller sp_send_dbmail returnerar ett fel.

[ @blind_copy_recipients = ] "blind_copy_recipients"

En semikolonavgränsad lista över e-postadresser att kopiera meddelandet till. Listan med mottagare av blindkopior är av typen varchar(max). Även om den här parametern är valfri måste minst en av @recipients, @copy_recipients eller @blind_copy_recipients anges eller sp_send_dbmail returnerar ett fel.

[ @from_address = ] "from_address"

Värdet för "från-adressen" för e-postmeddelandet. Det här är en valfri parameter som används för att åsidosätta inställningarna i e-postprofilen. Den här parametern är av typen varchar(max). SMTP-säkerhetsinställningar avgör om dessa åsidosättningar godkänns. Om ingen parameter anges är NULLstandardvärdet .

[ @reply_to = ] "reply_to"

Värdet för "svara på adress" för e-postmeddelandet. Den accepterar endast en e-postadress som ett giltigt värde. Det här är en valfri parameter som används för att åsidosätta inställningarna i e-postprofilen. Den här parametern är av typen varchar(max). SMTP-säkerhetsinställningar avgör om dessa åsidosättningar godkänns. Om ingen parameter anges är NULLstandardvärdet .

[ @subject = ] N'subject'

Ämnet för e-postmeddelandet. Ämnet är av typen nvarchar(255). Om inget ämne anges är standardvärdet "SQL Server Message".

[ @body = ] N'body'

Brödtexten i e-postmeddelandet. Meddelandetexten är av typen nvarchar(max), med standardvärdet NULL.

[ @body_format = ] "body_format"

Formatet på meddelandetexten. Parametern är av typen varchar(20), med standardvärdet NULL. När det anges anges rubrikerna för det utgående meddelandet för att indikera att meddelandetexten har det angivna formatet. Parametern kan innehålla något av följande värden:

• TEXT (standard)
• HTML

[ @importance = ] "prioritet"

Meddelandets betydelse. Parametern är av typen varchar(6). Parametern kan innehålla något av följande värden:

• Low
• Normal (standardinställning)
• High

[ @sensitivity = ] "känslighet"

Meddelandets känslighet. Parametern är av typen varchar(12). Parametern kan innehålla något av följande värden:

• Normal (standardinställning)
• Personal
• Private
• Confidential

[ @file_attachments = ] N'file_attachments'

En semikolonavgränsad lista med filnamn som ska bifogas till e-postmeddelandet. Filer i listan måste anges som absoluta sökvägar. Listan över bifogade filer är av typen nvarchar(max). Som standard begränsar Database Mail filbilagor till 1 MB per fil.

[ @query = ] N'query'

En fråga som ska köras. Resultatet av frågan kan bifogas som en fil eller inkluderas i brödtexten i e-postmeddelandet. Frågan är av typen nvarchar(max) och kan innehålla alla giltiga Transact-SQL-instruktioner. Frågan körs i en separat session, så lokala variabler i skriptanropet sp_send_dbmail är inte tillgängliga för frågan.

När du använder parametern @query måste det huvudnamn som körs sp_send_dbmail vara anslutet som en enskild person, inte som en del av en grupp, oavsett om det är ett Microsoft Entra-ID (tidigare Azure Active Directory) eller Windows Active Directory-grupp. SQL Server-inloggningar, Windows-identiteter och Microsoft Entra-identiteter kan köra frågan, men gruppmedlemmar kan inte köra frågan på grund av azure SQL Managed Instance-personifiering och kör som-begränsningar.

[ @execute_query_database = ] "execute_query_database"

Databaskontexten där den lagrade proceduren kör frågan. Parametern är av typen sysname, med standardvärdet för den aktuella databasen. Den här parametern gäller endast om @query anges.

[ @attach_query_result_as_file = ] attach_query_result_as_file

Anger om resultatuppsättningen för frågan returneras som en bifogad fil. @attach_query_result_as_file är av typen bit, med standardvärdet 0.

När värdet är 0inkluderas frågeresultatet i brödtexten i e-postmeddelandet efter innehållet i parametern @body . När värdet är 1returneras resultatet som en bifogad fil. Den här parametern gäller endast om @query anges.

[ @query_attachment_filename = ] N'query_attachment_filename'

Anger filnamnet som ska användas för resultatuppsättningen för den bifogade frågan. @query_attachment_filename är av typen nvarchar(255), med standardvärdet NULL. Den här parametern ignoreras när @attach_query_result_as_file är 0. När @attach_query_result_as_file är 1 och den här parametern är NULLskapar Database Mail ett godtyckligt filnamn.

[ @query_result_header = ] query_result_header

Anger om frågeresultatet innehåller kolumnrubriker. Värdet query_result_header är av typen bit. När värdet är 1innehåller frågeresultatet kolumnrubriker. När värdet är 0innehåller frågeresultatet inte kolumnrubriker. Den här parametern är 1som standard . Den här parametern gäller endast om @query anges.

Följande fel kan inträffa när du ställer in @query_result_header till 0 och anger @query_no_truncate till 1:

Msg 22050, Level 16, State 1, Line 12: Failed to initialize sqlcmd library with error number -2147024809.

[ @query_result_width = ] query_result_width

Radbredden, i tecken, som ska användas för att formatera resultatet av frågan. @query_result_width är av typen int, med standardvärdet 256. Det angivna värdet måste vara mellan 10 och 32767. Den här parametern gäller endast om @query anges.

[ @query_result_separator = ] "query_result_separator"

Tecknet som används för att separera kolumner i frågeutdata. Avgränsaren är av typen char(1). Standardvärdet är ' ' (blanksteg).

[ @exclude_query_output = ] exclude_query_output

Anger om du vill returnera utdata från frågekörningen i e-postmeddelandet. @exclude_query_output är bit, med standardvärdet 0. När den här parametern är 0skriver körningen av den sp_send_dbmail lagrade proceduren ut meddelandet som returneras som ett resultat av frågekörningen i konsolen. När den här parametern är 1skriver körningen av den sp_send_dbmail lagrade proceduren inte ut något av frågekörningsmeddelandena i konsolen.

[ @append_query_error = ] append_query_error

Anger om e-postmeddelandet ska skickas när ett fel returneras från frågan som anges i argumentet @query . @append_query_error är bit, med standardvärdet 0. När den här parametern är 1skickar Database Mail e-postmeddelandet och innehåller frågefelmeddelandet i brödtexten i e-postmeddelandet. När den här parametern är 0skickar Inte Database Mail e-postmeddelandet och sp_send_dbmail slutar med returkoden 1, vilket indikerar ett fel.

[ @query_no_truncate = ] query_no_truncate

Anger om frågan ska köras med det alternativ som undviker trunkering av datatyper med stor variabel längd (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, bild och användardefinierade datatyper). När du anger det innehåller frågeresultaten inte kolumnrubriker. Värdet @query_no_truncate är av typen bit. När värdet har 0 angetts eller inte har angetts trunkerar kolumnerna i frågan till 256 tecken. När värdet är 1trunkeras inte kolumnerna i frågan. Den här parametern är 0som standard .

[ @query_result_no_padding = ] query_result_no_padding

Typen är bit. Standardvärdet är 0. När du anger till 1är frågeresultatet inte vadderat, vilket kan minska filstorleken. Om du anger @query_result_no_padding parametern 1@query_result_width skriver parametern @query_result_no_padding över parametern @query_result_width .

I det här fallet uppstår inget fel.

Följande fel kan inträffa när du anger @query_result_no_padding till 1 och anger en parameter för @query_no_truncate:

Msg 22050, Level 16, State 1, Line 0: Failed to execute the query because the @query_result_no_append and @query_no_truncate options are mutually exclusive.

Om du anger @query_result_no_padding till 1 och anger parametern @query_no_truncate utlöses ett fel.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

Valfri utdataparameter returnerar mailitem_id meddelandets. @mailitem_id är av typen int.

Returnera kodvärden

En returkod för 0 betyder att det lyckades. Alla andra värden innebär fel. Felkoden för instruktionen som misslyckades lagras i variabeln @@ERROR .

Resultatuppsättning

Vid lyckat resultat returnerar meddelandet "E-post i kö".

Anmärkningar

Före användning måste Database Mail vara aktiverat med hjälp av guiden För konfiguration av databasmeddelande eller sp_configure.

sysmail_stop_sp stoppar Database Mail genom att stoppa de Service Broker-objekt som det externa programmet använder. sp_send_dbmailaccepterar fortfarande e-post när Database Mail stoppas med .sysmail_stop_sp Om du vill starta Database Mail använder du sysmail_start_sp.

När @profile inte har angetts sp_send_dbmail använder en standardprofil. Om användaren som skickar e-postmeddelandet har en privat standardprofil använder Database Mail den profilen. Om användaren inte har någon privat standardprofil sp_send_dbmail använder den offentliga standardprofilen. Om det inte finns någon privat standardprofil för användaren och ingen offentlig standardprofil sp_send_dbmail returneras ett fel.

sp_send_dbmail stöder inte e-postmeddelanden utan innehåll. Om du vill skicka ett e-postmeddelande måste du ange minst en av @body, @query, @file_attachments eller @subject. Annars sp_send_dbmail returnerar ett fel.

Database Mail körs i säkerhetskontexten för tjänstkontot för SQL Server. Därför kan användare som autentiseras med SQL Server-autentisering inte bifoga filer med hjälp av @file_attachments. Windows tillåter inte att SQL Server anger autentiseringsuppgifter från en fjärrdator till en annan fjärrdator. Därför kanske Database Mail inte kan bifoga filer från en nätverksresurs i de fall då kommandot körs från en annan dator än den dator som SQL Server körs på.

Om både @query och @file_attachments anges och filen inte kan hittas, körs frågan fortfarande men e-postmeddelandet skickas inte.

När en fråga har angetts formateras resultatuppsättningen som infogad text. Binära data i resultatet skickas i hexadecimalt format.

Parametrarna @recipients, @copy_recipients och @blind_copy_recipients är semikolonavgränsade listor med e-postadresser. Minst en av dessa parametrar måste anges eller sp_send_dbmail returnera ett fel.

När du sp_send_dbmail kör utan en transaktionskontext startar Och genomför Database Mail en implicit transaktion. När du kör inifrån en befintlig transaktion förlitar sig Database Mail på att användaren antingen checkar sp_send_dbmail in eller återställer eventuella ändringar. Den startar inte en inre transaktion.

Permissions

Kör behörigheter som sp_send_dbmail standard för alla medlemmar i databasrollen msdbDatabaseMailUserRole i databasen. Men när användaren som skickar meddelandet inte har behörighet att använda profilen för begäran returnerar sp_send_dbmail ett fel och skickar inte meddelandet.

Examples

A. Skicka ett e-postmeddelande

Det här exemplet skickar ett e-postmeddelande till din vän med hjälp av e-postadressen myfriend@adventure-works.com. Meddelandet har ämnet Automated Success Message. Brödtexten i meddelandet innehåller meningen The stored procedure finished successfully.

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

B. Skicka ett e-postmeddelande med resultatet av en fråga

Det här exemplet skickar ett e-postmeddelande till din vän med hjälp av e-postadressen yourfriend@adventure-works.com. Meddelandet har ämnet Work Order Countoch kör en fråga som visar antalet arbetsorder med DueDate mindre än två dagar efter den 30 april 2022. Database Mail bifogar resultatet som en textfil.

EXECUTE msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'yourfriend@adventure-works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2022.Production.WorkOrder
                  WHERE DueDate > ''2022-04-30''
                  AND DATEDIFF(dd, ''2022-04-30'', DueDate) < 2', @subject = 'Work Order Count', @attach_query_result_as_file = 1;

C. Skicka ett HTML-e-postmeddelande

Det här exemplet skickar ett e-postmeddelande till din vän med hjälp av e-postadressen yourfriend@adventure-works.com. Meddelandet har ämnet Work Order Listoch innehåller ett HTML-dokument som visar arbetsorder med DueDate mindre än två dagar efter den 30 april 2022. Database Mail skickar meddelandet i HTML-format.

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
            INNER JOIN AdventureWorks.Production.Product AS p
                ON wo.ProductID = p.ProductID
            WHERE DueDate > '2022-04-30'
                AND DATEDIFF(dd, '2022-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>';

EXECUTE msdb.dbo.sp_send_dbmail
    @recipients = 'yourfriend@adventure-works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML';

Relaterat innehåll

• Databas-e-post
• Konfigurationsobjekt för databaspost
• Lagrade procedurer för Database Mail (Transact-SQL)
• Externt program för Database Mail
• sp_addrolemember (Transact-SQL)