sp_send_dbmail (Transact-SQL)

[アーティクル]
12/20/2023

適用対象: SQL Server Azure SQL Managed Instance

指定した受信者に電子メールメッセージを送信します。メッセージには、クエリ結果セット、添付ファイル、またはその両方が含まれる場合があります。メールがデータベースメールキューに正常に配置されると、sp_send_dbmailメッセージの内容がmailitem_id返されます。このストアドプロシージャはデータベースにあります msdb 。

Transact-SQL 構文表記規則

構文

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 ]
[ ; ]

引数

[ @profile_name = ] 'profile_name'

メッセージを送信するプロファイルの名前。 @profile_nameは sysname 型で、既定値は NULL. @profile_nameは、既存のデータベースメールプロファイルの名前である必要があります。 @profile_nameが指定されていない場合は、sp_send_dbmail現在のユーザーの既定のプライベートプロファイルを使用します。ユーザーが既定のプライベートプロファイルを持っていない場合は、 sp_send_dbmail データベースの既定のパブリックプロファイルを msdb 使用します。ユーザーに既定のプライベートプロファイルがなく、データベースの既定のパブリックプロファイルがない場合は、 @profile_name を指定する必要があります。

[ @recipients = ] 'recipients'

メッセージを送信する電子メールアドレスのセミコロン区切りのリスト。受信者リストの型 は varchar(max)です。このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか sp_send_dbmail 、エラーを返す必要があります。

[ @copy_recipients = ] 'copy_recipients'

メッセージのカーボンコピー先の電子メールアドレスのセミコロン区切りのリスト。コピー受信者リストの型 は varchar(max)です。このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか sp_send_dbmail 、エラーを返す必要があります。

[ @blind_copy_recipients = ] 'blind_copy_recipients'

メッセージのコピー先のブラインドカーボンの電子メールアドレスのセミコロン区切りのリスト。ブラインドコピー受信者リストの型 は varchar(max)です。このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか sp_send_dbmail 、エラーを返す必要があります。

[ @from_address = ] 'from_address'

電子メールメッセージの "from address" の値。これは、メールプロファイルの設定をオーバーライドするために使用される省略可能なパラメーターです。このパラメーターの型 は varchar(max)です。オーバーライドが許可されるかどうかは、SMTP のセキュリティ設定によって決まります。パラメーターが指定されていない場合、既定値は NULL.

[ @reply_to = ] 'reply_to'

電子メールメッセージの "アドレスへの返信" の値。有効な値として受け取る電子メールアドレスは 1 つだけです。これは、メールプロファイルの設定をオーバーライドするために使用される省略可能なパラメーターです。このパラメーターの型 は varchar(max)です。オーバーライドが許可されるかどうかは、SMTP のセキュリティ設定によって決まります。パラメーターが指定されていない場合、既定値は NULL.

[ @subject = ] N'subject'

電子メールメッセージの件名です。サブジェクトは nvarchar(255) 型です。件名が指定されていない場合、既定値は "SQL Server メッセージ" です。

[ @body = ] N'body'

電子メールメッセージの本文。メッセージ本文は nvarchar(max) 型で、既定値は NULL.

[ @body_format = ] 'body_format'

メッセージ本文の形式。パラメーターは varchar(20) 型で、既定値は NULL. 指定した場合、送信メッセージのヘッダーには、メッセージの本文が指定の形式であることを示す文字列が設定されます。パラメーターには、次のいずれかの値が含まれる場合があります。

TEXT (既定)
HTML

[ @importance = ] 'importance'

メッセージの重要度。パラメーターは varchar(6) 型です。パラメーターには、次のいずれかの値が含まれる場合があります。

Low
Normal (既定)
High

[ @sensitivity = ] 'sensitivity'

メッセージの秘密度。パラメーターは varchar(12) 型です。パラメーターには、次のいずれかの値が含まれる場合があります。

Normal (既定)
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

電子メールメッセージに添付するファイル名のセミコロン区切りのリスト。リスト内のファイルは絶対パスとして指定する必要があります。添付ファイルの一覧は nvarchar(max) 型です。既定では、データベースメールの添付ファイルは 1 ファイルにつき 1 MB に制限されます。

重要

このパラメーターは、ローカルファイルシステムにアクセスできないため、Azure SQL Managed Instance では使用できません。

[ @query = ] N'query'

実行するクエリ。クエリの結果は、ファイルとして添付することも、電子メールメッセージの本文に含めることもできます。クエリは nvarchar(max) 型で、任意の有効な Transact-SQL ステートメントを含めることができます。クエリは別のセッションで実行されるため、スクリプト呼び出し sp_send_dbmail のローカル変数はクエリで使用できません。

@query パラメーターを使用する場合、実行sp_send_dbmailするプリンシパルは、Microsoft Entra ID (旧称 Azure Active Directory) グループか Windows Active Directory グループかにかかわらず、グループの一部としてではなく、個人として接続する必要があります。 SQL Server ログイン、Windows ID、および Microsoft Entra ID はクエリを実行できますが、Azure SQL Managed Instance の偽装と EXECUTE AS の制限により、グループメンバーは実行できません。

[ @execute_query_database = ] 'execute_query_database'

ストアドプロシージャがクエリを実行するデータベースコンテキスト。このパラメーターは sysname 型で、既定値は現在のデータベースです。このパラメーターは、@queryが指定されている場合にのみ適用されます。

[ @attach_query_result_as_file = ] attach_query_result_as_file

クエリの結果セットを添付ファイルとして返すかどうかを指定します。 @attach_query_result_as_fileは bit 型で、既定値は 0.

値が0指定されている場合、@body パラメーターの内容の後に、電子メールメッセージの本文にクエリ結果が含まれます。値 1が指定されている場合、結果は添付ファイルとして返されます。このパラメーターは、@queryが指定されている場合にのみ適用されます。

[ @query_attachment_filename = ] N'query_attachment_filename'

クエリ添付ファイルの結果セットに使用するファイル名を指定します。 @query_attachment_filenameは nvarchar(255) 型で、既定値は NULL. @attach_query_result_as_fileの場合、このパラメーターは0無視されます。 @attach_query_result_as_fileが1指定され、このパラメーターが指定されている場合、NULLデータベースメールは任意のファイル名を作成します。

[ @query_result_header = ] query_result_header

クエリの結果に列のヘッダーを含めるかどうかを指定します。 query_result_header値はビット型です。値が指定されている場合、 1クエリ結果には列ヘッダーが含まれます。値が指定されている 0場合、クエリ結果には列ヘッダーは含まれません。このパラメーターの既定値は 1. このパラメーターは、@queryが指定されている場合にのみ適用されます。

@query_result_headerを設定 し、@query_no_truncate を 0 次のように設定 すると、次のエラーが 発生する 1可能性があります。

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

[ @query_result_width = ] query_result_width

クエリの結果の書式設定に使用する行の幅 (文字単位)。 @query_result_widthは int 型で、既定値は 256. 指定する値は、次の値の32767間10である必要があります。このパラメーターは、@queryが指定されている場合にのみ適用されます。

[ @query_result_separator = ] 'query_result_separator'

クエリの出力で列の区切りに使用された文字。区切り記号は char(1) 型です。既定値は ' ' (スペース) です。

[ @exclude_query_output = ] exclude_query_output

電子メールメッセージ内にクエリ実行の出力を返すかどうかを指定します。 @exclude_query_outputはビットで、既定値は 0. このパラメーターを 0指定すると、ストアドプロシージャの sp_send_dbmail 実行によって、コンソールでのクエリ実行の結果として返されるメッセージが出力されます。このパラメーターの 1場合、ストアドプロシージャを sp_send_dbmail 実行しても、コンソールにクエリ実行メッセージは出力されません。

[ @append_query_error = ] append_query_error

@query引数で指定したクエリからエラーが返されたときに電子メールを送信するかどうかを指定します。 @append_query_errorはビットで、既定値は 0. このパラメーターを1指定すると、データベースメールは電子メールメッセージを送信し、電子メールメッセージの本文にクエリエラーメッセージを含めます。このパラメーターが0指定されている場合、データベースメールは電子メールメッセージを送信せず、sp_send_dbmailエラーを示すリターンコード1で終わります。

[ @query_no_truncate = ] query_no_truncate

大きな可変長データ型 (varchar(max)、nvarchar(max)、varbinary(max)、xml、text、ntext、image、およびユーザー定義データ型の切り捨てを回避するオプションを使用してクエリを実行するかどうかを指定します。設定すると、クエリ結果に列ヘッダーは含まれません。 @query_no_truncate値はビット型です。値 0 が指定されていない場合、クエリ内の列は 256 文字に切り捨てられます。値が指定されている 1場合、クエリ内の列は切り捨てられません。このパラメーターの既定値は 0.

Note

大量のデータと共に使用すると、 @query_no_truncate オプションによって追加のリソースが消費され、サーバーのパフォーマンスが低下する可能性があります。

[ @query_result_no_padding = ] query_result_no_padding

型はビットです。既定値は、0 です。に 1設定すると、クエリ結果が埋め込まれないので、ファイルサイズが小さくなる可能性があります。 @query_result_width パラメーターを設定@query_result_no_paddingすると、@query_result_no_padding パラメーターによって @query_result_width パラメーターが上書きされます。1

この場合、エラーは発生しません。

@query_result_no_paddingを設定し、@query_no_truncate1のパラメーターを指定すると、次のエラーが発生する可能性があります。

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.

@query_result_no_padding1を設定し、@query_no_truncate パラメーターを設定すると、エラーが発生します。

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

オプションの出力パラメーターは、メッセージの mailitem_id 値を返します。 @mailitem_idは int 型です。

リターンコードの値

戻りコードは成功を 0 意味します。その他の値は失敗を意味します。失敗したステートメントのエラーコードが変数に @@ERROR 格納されます。

結果セット

成功すると、"メールがキューに登録されました。" というメッセージが返されます。

解説

使用する前に、データベースメール構成ウィザードsp_configureを使用してデータベースメールを有効にする必要があります。

sysmail_stop_spは、外部プログラムが使用する Service Broker オブジェクトを停止することによって、データベースメールを停止します。 sp_send_dbmailを使用sysmail_stop_spしてデータベースメールが停止した場合でもメールを受け入れます。データベースメールを開始するには、次を使用しますsysmail_start_sp。

@profileが指定されていない場合は、sp_send_dbmail既定のプロファイルを使用します。電子メールメッセージを送信するユーザーに既定のプライベートプロファイルがある場合、データベースメールではそのプロファイルが使用されます。ユーザーに既定のプライベートプロファイルがない場合は、 sp_send_dbmail 既定のパブリックプロファイルを使用します。ユーザーの既定のプライベートプロファイルがなく、既定のパブリックプロファイルがない場合は、 sp_send_dbmail エラーを返します。

sp_send_dbmail では、コンテンツのない電子メールメッセージはサポートされません。電子メールメッセージを送信するには、少なくとも 1 つの@body、@query、@file_attachments、または@subjectを指定する必要があります。それ以外の場合は、 sp_send_dbmail エラーを返します。

データベースメールは、現在のユーザーの Microsoft Windows セキュリティコンテキストを使用して、ファイルへのアクセスを制御します。そのため、SQL Server 認証で認証されたユーザーは、@file_attachmentsを使用してファイルを添付できません。 Windows では、SQL Server がリモートコンピューターから別のリモートコンピューターに資格情報を提供することはできません。そのため、SQL Server が実行されているコンピューター以外のコンピューターからコマンドを実行した場合、データベースメールはネットワーク共有からファイルをアタッチできない可能性があります。

@queryと@file_attachmentsの両方が指定されていて、ファイルが見つからない場合、クエリは引き続き実行されますが、電子メールは送信されません。

クエリを指定すると、結果セットはインラインテキストとして書式設定されます。結果セットにあるバイナリデータは 16 進数形式で送信されます。

パラメーター @recipients、 @copy_recipients、および @blind_copy_recipients は、電子メールアドレスのセミコロン区切りのリストです。これらのパラメーターのうち少なくとも 1 つを指定するか sp_send_dbmail 、エラーを返す必要があります。

トランザクションコンテキストなしで実行するsp_send_dbmail場合、データベースメールは暗黙的なトランザクションを開始してコミットします。既存のトランザクション内から実行するsp_send_dbmail場合、データベースメールはユーザーに依存して、変更をコミットまたはロールバックします。内部トランザクションは開始されません。

アクセス許可

データベース内の DatabaseMailUser データベースロールのすべてのメンバーに対sp_send_dbmailする既定のmsdb実行アクセス許可。ただし、メッセージを送信するユーザーに要求のプロファイルを使用するアクセス許可がない場合は、エラーが返され、 sp_send_dbmail メッセージは送信されません。

例

A. 電子メールメッセージを送信する

この例では、電子メールアドレスを使用して、友人に電子メールメッセージを送信します myfriend@adventure-works.com。メッセージには件名 Automated Success Messageがあります。メッセージの本文には、文 The stored procedure finished successfullyが含まれています。

EXEC 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. クエリの結果を含む電子メールメッセージを送信する

この例では、電子メールアドレスを使用して、友人に電子メールメッセージを送信します yourfriend@adventure-works.com。このメッセージには件名 Work Order Countがあり、2022 年 4 月 30 日から 2 日未満の作業指示書 DueDate の数を示すクエリが実行されます。データベースメール結果をテキストファイルとして添付します。

EXEC 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: HTML 電子メールメッセージを送信する

この例では、電子メールアドレスを使用して、友人に電子メールメッセージを送信します yourfriend@adventure-works.com。メッセージには件名 Work Order Listがあり、2022 年 4 月 30 日から 2 日以内の作業指示 DueDate を示す HTML ドキュメントが含まれています。データベースメールでは、このメッセージが HTML 形式で送信されます。

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

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

sp_send_dbmail (Transact-SQL)

構文

引数

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @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'file_attachments'

[ @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 ]

リターンコードの値

結果セット

解説

アクセス許可

例

A. 電子メールメッセージを送信する

B. クエリの結果を含む電子メールメッセージを送信する

C: HTML 電子メールメッセージを送信する

フィードバック

フィードバック

その他のリソース

sp_send_dbmail (Transact-SQL)

構文

引数

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @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'file_attachments'

[ @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 ]

リターン コードの値

結果セット

解説

アクセス許可

例

A. 電子メール メッセージを送信する

B. クエリの結果を含む電子メール メッセージを送信する

C: HTML 電子メール メッセージを送信する

関連するコンテンツ

フィードバック

フィードバック

その他のリソース

リターンコードの値

A. 電子メールメッセージを送信する

B. クエリの結果を含む電子メールメッセージを送信する

C: HTML 電子メールメッセージを送信する