sp_send_dbmail (Transact-SQL)

Van toepassing op:SQL ServerAzure SQL Managed Instance

Hiermee wordt een e-mailbericht verzonden naar de opgegeven geadresseerden. Het bericht bevat mogelijk een queryresultatenset, bestandsbijlagen of beide. Wanneer e-mail is geplaatst in de database-e-mailwachtrij, sp_send_dbmail wordt het mailitem_id bericht geretourneerd. Deze opgeslagen procedure bevindt zich in de msdb database.

Transact-SQL syntaxis-conventies

Syntaxis

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'

De naam van het profiel waaruit het bericht moet worden verzonden. De @profile_name is van het type sysname, met een standaardwaarde van NULL. De @profile_name moet de naam van een bestaand Database Mail-profiel zijn. Als er geen @profile_name is opgegeven, sp_send_dbmail gebruikt u het standaardprofiel voor privé voor de huidige gebruiker. Als de gebruiker geen standaard privéprofiel heeft, sp_send_dbmail gebruikt u het standaard openbare profiel voor de msdb database. Als de gebruiker geen standaard privéprofiel heeft en er geen standaard openbaar profiel voor de database is, moet @profile_name worden opgegeven.

[ @recipients = ] 'geadresseerden'

Een door puntkomma's gescheiden lijst met e-mailadressen om het bericht naar te verzenden. De lijst met geadresseerden is van het type varchar(max). Hoewel deze parameter optioneel is, moet ten minste één van @recipients, @copy_recipients of @blind_copy_recipients worden opgegeven, of sp_send_dbmail wordt een fout geretourneerd.

[ @copy_recipients = ] 'copy_recipients'

Een door puntkomma's gescheiden lijst met e-mailadressen om het bericht naar carbon te kopiëren. De lijst met geadresseerden voor kopiëren is van het type varchar(max). Hoewel deze parameter optioneel is, moet ten minste één van @recipients, @copy_recipients of @blind_copy_recipients worden opgegeven, of sp_send_dbmail wordt een fout geretourneerd.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Een door puntkomma's gescheiden lijst met e-mailadressen om het bericht naar blind carbon te kopiëren. De lijst met geadresseerden voor blinde kopie is van het type varchar(max). Hoewel deze parameter optioneel is, moet ten minste één van @recipients, @copy_recipients of @blind_copy_recipients worden opgegeven, of sp_send_dbmail wordt een fout geretourneerd.

[ @from_address = ] 'from_address'

De waarde van het 'van-adres' van het e-mailbericht. Dit is een optionele parameter die wordt gebruikt om de instellingen in het e-mailprofiel te overschrijven. Deze parameter is van het type varchar(max). Smtp-beveiligingsinstellingen bepalen of deze onderdrukkingen worden geaccepteerd. Als er geen parameter is opgegeven, is de standaardwaarde NULL.

[ @reply_to = ] 'reply_to'

De waarde van het antwoordadres van het e-mailbericht. Het accepteert slechts één e-mailadres als een geldige waarde. Dit is een optionele parameter die wordt gebruikt om de instellingen in het e-mailprofiel te overschrijven. Deze parameter is van het type varchar(max). Smtp-beveiligingsinstellingen bepalen of deze onderdrukkingen worden geaccepteerd. Als er geen parameter is opgegeven, is de standaardwaarde NULL.

[ @subject = ] N'subject'

Het onderwerp van het e-mailbericht. Het onderwerp is van het type nvarchar(255). Als er geen onderwerp is opgegeven, is de standaardwaarde 'SQL Server-bericht'.

[ @body = ] N'body'

De hoofdtekst van het e-mailbericht. De berichttekst is van het type nvarchar(max), met een standaardwaarde van NULL.

[ @body_format = ] 'body_format'

De indeling van de hoofdtekst van het bericht. De parameter is van het type varchar(20), met een standaardwaarde van NULL. Wanneer dit is opgegeven, worden de kopteksten van het uitgaande bericht ingesteld om aan te geven dat de hoofdtekst van het bericht de opgegeven indeling heeft. De parameter kan een van de volgende waarden bevatten:

• TEKST (standaard)
• HTML

[ @importance = ] "urgentie"

Het belang van het bericht. De parameter is van het type varchar(6). De parameter kan een van de volgende waarden bevatten:

• Low
• Normal (standaard)
• High

[ @sensitivity = ] 'gevoeligheid'

De gevoeligheid van het bericht. De parameter is van het type varchar(12). De parameter kan een van de volgende waarden bevatten:

• Normal (standaard)
• Personal
• Private
• Confidential

[ @file_attachments = ] N'file_attachments'

Een door puntkomma's gescheiden lijst met bestandsnamen die moeten worden toegevoegd aan het e-mailbericht. Bestanden in de lijst moeten worden opgegeven als absolute paden. De lijst met bijlagen is van het type nvarchar(max). Database Mail beperkt standaard bestandsbijlagen tot 1 MB per bestand.

[ @query = ] N'query'

Een query die moet worden uitgevoerd. De resultaten van de query kunnen worden bijgevoegd als een bestand of worden opgenomen in de hoofdtekst van het e-mailbericht. De query is van het type nvarchar(max), en kan geldige Transact-SQL instructies bevatten. De query wordt uitgevoerd in een afzonderlijke sessie, zodat lokale variabelen in het aanroepen sp_send_dbmail van scripts niet beschikbaar zijn voor de query.

Wanneer u de parameter @query gebruikt, moet de principal die wordt uitgevoerd sp_send_dbmail , worden verbonden als een persoon, niet als onderdeel van een groep, ongeacht of een Microsoft Entra-id (voorheen Azure Active Directory) of Windows Active Directory-groep. Sql Server-aanmeldingen, Windows-identiteiten en Microsoft Entra-identiteiten kunnen de query uitvoeren, maar groepsleden kunnen niet, vanwege imitatie van Azure SQL Managed Instance en EXECUTE AS-beperkingen.

[ @execute_query_database = ] 'execute_query_database'

De databasecontext waarin de opgeslagen procedure de query uitvoert. De parameter is van het type sysname, met een standaardwaarde van de huidige database. Deze parameter is alleen van toepassing als @query is opgegeven.

[ @attach_query_result_as_file = ] attach_query_result_as_file

Hiermee geeft u op of de resultatenset van de query wordt geretourneerd als een bijgevoegd bestand. @attach_query_result_as_file is van het type bit, met een standaardwaarde van 0.

Wanneer de waarde is 0, worden de queryresultaten opgenomen in de hoofdtekst van het e-mailbericht, na de inhoud van de parameter @body . Wanneer de waarde is 1, worden de resultaten geretourneerd als bijlage. Deze parameter is alleen van toepassing als @query is opgegeven.

[ @query_attachment_filename = ] N'query_attachment_filename'

Hiermee geeft u de bestandsnaam op die moet worden gebruikt voor de resultatenset van de querybijlage. @query_attachment_filename is van het type nvarchar(255), met een standaardwaarde van NULL. Deze parameter wordt genegeerd wanneer @attach_query_result_as_file is 0. Wanneer @attach_query_result_as_file is 1 en deze parameter is NULL, maakt Database Mail een willekeurige bestandsnaam.

[ @query_result_header = ] query_result_header

Hiermee geeft u op of de queryresultaten kolomkoppen bevatten. De query_result_header waarde is van het type bit. Wanneer de waarde is 1, bevatten queryresultaten kolomkoppen. Wanneer de waarde is 0, bevatten queryresultaten geen kolomkoppen. Deze parameter is standaard ingesteld op 1. Deze parameter is alleen van toepassing als @query is opgegeven.

De volgende fout kan optreden wanneer u @query_result_header instelt0 op en @query_no_truncate instelt op 1:

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

[ @query_result_width = ] query_result_width

De lijnbreedte, in tekens, die moet worden gebruikt voor het opmaken van de resultaten van de query. De @query_result_width is van het type int, met een standaardwaarde van 256. De opgegeven waarde moet tussen 10 en 32767. Deze parameter is alleen van toepassing als @query is opgegeven.

[ @query_result_separator = ] 'query_result_separator'

Het teken dat wordt gebruikt om kolommen in de queryuitvoer te scheiden. Het scheidingsteken is van het type char(1). Standaard ingesteld op ' ' (spatie).

[ @exclude_query_output = ] exclude_query_output

Hiermee geeft u op of de uitvoer van de queryuitvoering in het e-mailbericht moet worden geretourneerd. @exclude_query_output is bit, met een standaardwaarde van 0. Wanneer deze parameter is 0, drukt de uitvoering van de sp_send_dbmail opgeslagen procedure het bericht af dat wordt geretourneerd als gevolg van de uitvoering van de query op de console. Wanneer deze parameter is 1, wordt tijdens de uitvoering van de sp_send_dbmail opgeslagen procedure geen berichten van de queryuitvoering op de console afgedrukt.

[ @append_query_error = ] append_query_error

Hiermee geeft u op of het e-mailbericht moet worden verzonden wanneer een fout wordt geretourneerd uit de query die is opgegeven in het argument @query . @append_query_error is bit, met een standaardwaarde van 0. Als deze parameter is 1, verzendt Database Mail het e-mailbericht en bevat het queryfoutbericht in de hoofdtekst van het e-mailbericht. Als deze parameter is 0, verzendt Database Mail het e-mailbericht niet en sp_send_dbmail eindigt met retourcode 1, wat een fout aangeeft.

[ @query_no_truncate = ] query_no_truncate

Hiermee geeft u op of de query moet worden uitgevoerd met de optie die afkapping van gegevenstypen met een grote variabele lengte (varchar(max), nvarchar(max), varbinary(max), xml, tekst, ntext, afbeelding en door de gebruiker gedefinieerde gegevenstypen voorkomt. Bij het instellen bevatten queryresultaten geen kolomkoppen. De @query_no_truncate waarde is van het type bit. Wanneer de waarde al dan niet is 0 opgegeven, worden kolommen in de query afgekapt tot 256 tekens. Wanneer de waarde is 1, worden kolommen in de query niet afgekapt. Deze parameter is standaard ingesteld op 0.

[ @query_result_no_padding = ] query_result_no_padding

Het type is bit. De standaardwaarde is 0. Wanneer u deze instelt 1, worden de queryresultaten niet opgevuld, waardoor de bestandsgrootte mogelijk wordt verkleind. Als u deze optie instelt @query_result_no_padding1 en de parameter @query_result_width instelt, overschrijft de parameter @query_result_no_padding de parameter @query_result_width .

In dit geval treedt er geen fout op.

De volgende fout kan optreden bij het instellen van @query_result_no_padding en 1 het instellen van een parameter voor @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.

Als u de @query_result_no_padding1 instelt en u de parameter @query_no_truncate instelt, wordt er een fout gegenereerd.

[ @mailitem_id = ] mailitem_id [ UITVOER ]

Met de optionele uitvoerparameter wordt het mailitem_id bericht geretourneerd. @mailitem_id is van het type int.

Codewaarden retourneren

Een retourcode van het succes van 0 de middelen. Elke andere waarde betekent fout. De foutcode voor de instructie die is mislukt, wordt opgeslagen in de @@ERROR variabele.

Resultaatset

Retourneert het bericht 'E-mail in wachtrij'.

Opmerkingen

Voordat u Database Mail gebruikt, moet Database Mail zijn ingeschakeld met behulp van de wizard Database Mail configureren, of sp_configure.

sysmail_stop_sp stopt Database Mail door de Service Broker-objecten te stoppen die door het externe programma worden gebruikt. sp_send_dbmail accepteert nog steeds e-mail wanneer Database Mail niet meer wordt gebruikt sysmail_stop_sp. Als u Database Mail wilt starten, gebruikt u sysmail_start_sp.

Wanneer @profile niet is opgegeven, sp_send_dbmail wordt een standaardprofiel gebruikt. Als de gebruiker die het e-mailbericht verzendt, een standaardprofiel heeft, gebruikt Database Mail dat profiel. Als de gebruiker geen standaard privéprofiel heeft, sp_send_dbmail gebruikt u het standaard openbare profiel. Als er geen standaard privéprofiel is voor de gebruiker en geen standaard openbaar profiel, sp_send_dbmail wordt er een fout geretourneerd.

sp_send_dbmail biedt geen ondersteuning voor e-mailberichten zonder inhoud. Als u een e-mailbericht wilt verzenden, moet u ten minste één van @body, @query, @file_attachments of @subject opgeven. sp_send_dbmail Anders wordt een fout geretourneerd.

Database Mail wordt uitgevoerd in de beveiligingscontext van het serviceaccount voor SQL Server. Daarom kunnen gebruikers die zijn geverifieerd met SQL Server-verificatie geen bestanden bijvoegen met behulp van @file_attachments. In Windows kan SQL Server geen referenties opgeven van een externe computer naar een andere externe computer. Database Mail kan daarom mogelijk geen bestanden bijvoegen vanaf een netwerkshare in gevallen waarin de opdracht wordt uitgevoerd vanaf een andere computer dan de computer waarop SQL Server wordt uitgevoerd.

Als zowel @query als @file_attachments zijn opgegeven en het bestand niet kan worden gevonden, wordt de query nog steeds uitgevoerd, maar wordt het e-mailbericht niet verzonden.

Wanneer een query is opgegeven, wordt de resultatenset opgemaakt als inlinetekst. Binaire gegevens in het resultaat worden verzonden in hexadecimale indeling.

De parameters @recipients, @copy_recipients en @blind_copy_recipients zijn door puntkomma's gescheiden lijsten met e-mailadressen. Ten minste één van deze parameters moet worden opgegeven of sp_send_dbmail retourneert een fout.

Bij uitvoering sp_send_dbmail zonder transactiecontext start Database Mail een impliciete transactie en voert deze door. Bij het sp_send_dbmail uitvoeren vanuit een bestaande transactie is Database Mail afhankelijk van de gebruiker om wijzigingen door te voeren of terug te draaien. Er wordt geen interne transactie gestart.

Permissions

Voer standaard machtigingen uit voor sp_send_dbmail alle leden van de databaserol DatabaseMailUserRole in de msdb database. Wanneer de gebruiker die het bericht verzendt, echter niet gemachtigd is om het profiel voor de aanvraag te gebruiken, sp_send_dbmail wordt er een fout geretourneerd en wordt het bericht niet verzonden.

Voorbeelden

Eén. Een e-mailbericht verzenden

In dit voorbeeld wordt een e-mailbericht naar uw vriend verzonden met behulp van het e-mailadres myfriend@adventure-works.com. Het bericht heeft het onderwerp Automated Success Message. De hoofdtekst van het bericht bevat de zin 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. Een e-mailbericht verzenden met de resultaten van een query

In dit voorbeeld wordt een e-mailbericht naar uw vriend verzonden met behulp van het e-mailadres yourfriend@adventure-works.com. Het bericht heeft het onderwerp Work Order Counten voert een query uit die het aantal werkorders weergeeft met minder DueDate dan twee dagen na 30 april 2022. Database Mail voegt het resultaat als tekstbestand toe.

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. Een HTML-e-mailbericht verzenden

In dit voorbeeld wordt een e-mailbericht naar uw vriend verzonden met behulp van het e-mailadres yourfriend@adventure-works.com. Het bericht heeft het onderwerp Work Order Listen bevat een HTML-document met de werkorders met een DueDate periode van minder dan twee dagen na 30 april 2022. Database Mail verzendt het bericht in HTML-indeling.

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

Verwante inhoud

• Database-e-mail
• Database Mail-configuratieobjecten
• Opgeslagen procedures voor Database Mail (Transact-SQL)
• Extern programma Database Mail
• sp_addrolemember (Transact-SQL)