xp_sendmail (Transact-SQL)

指定した受信者に電子メール メッセージを送信します。メッセージにはクエリ結果セットを添付できます。この拡張ストアド プロシージャでは、メッセージの送信に SQL Mail が使用されます。

注
この機能は、将来のバージョンの Microsoft SQL Server では削除される予定です。新しい開発作業では、この機能の使用を避け、現在この機能を使用しているアプリケーションは修正するようにしてください。 SQL Server からメールを送信するには、データベース メールを使用してください。

Transact-SQL 構文表記規則

構文

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

引数

• [ @recipients=] **'**recipients [ ;...n] '
  メールの受信者をセミコロン区切りのリストで指定します。

• [ @message=] 'message'
  送信するメッセージの本文を指定します。messageの最大サイズは 8,000 バイトです。

• [ @query=] 'query'
  結果をメールで送信する、有効な SQL Server クエリを指定します。xp_sendmail では query パラメータにバインドされた接続が使用されます。SQL Mail で行われる query 接続は、xp_sendmail 要求を実行したクライアントが保持するロックによってブロックされることはありません。これにより、xp_sendmail をトリガ内部から簡単に使用できます。ただし、inserted および deleted 論理テーブルはトリガ内部でしか使用できないため、query ステートメントではこれらのテーブルを参照できません。queryの最大サイズは 8,000 バイトです。

• [ @attachments=] 'attachments [ ;...n] '
  メール メッセージに添付するファイルをセミコロン区切りのリストで指定します。@attach_results が TRUE のときに @query パラメータを使用する場合、@attachments パラメータではメール メッセージに添付するファイルを 1 つだけ指定できます。この場合、2 つ以上のファイルを送信するには、添付ファイルごとに xp_sendmail を実行する必要があります。

• [ @copy_recipients=] **'**copy_recipients [ ;...n] '
  メールのコピーの受信者を、セミコロン区切りのリストで指定します。

• [ @blind_copy_recipients=] **'**blind_copy_recipients[ ;...n] '
  メールのブラインド コピーの受信者を、セミコロン区切りのリストで指定します。省略可能です。

• [ @subject=] 'subject'
  メールの件名を指定します。subjectを指定しない場合、既定値は "SQL Server メッセージ" となります。

• [ @type = ] 'type'
  MAPI メール定義に基づく入力メッセージの型を指定します。

  IP[ M|C ].Vendorname.subclass

  type が NULL の場合、xp_sendmail ではメッセージ型 IPM が使用されます。IPM で始まるメッセージ型はメール クライアントの受信トレイに表示され、xp_findnextmsg を使用して検索や内容確認を行えます。IPC で始まるメッセージ型は、メール クライアントの受信トレイには表示されず、検索や内容確認には type パラメータを設定する必要があります。既定値は NULL です。SQL Mail では、IPM および IPC のメッセージ型がサポートされます。

• [ @attach_results=] 'attach_value'
  省略可能なパラメータです。クエリの結果セットをメールの本文に追加するのではなく、メールの添付ファイルとして送信します。@attachments が NULL でなく、@attach_results が TRUE の場合は、attachments の最初のファイル名が結果のファイル名として使用されます。@attachments が NULL の場合は、拡張子 .txt のファイル名が生成されます。既定値は FALSE です。これは、結果セットをメッセージに添付することを示します。

• [ @no_output=] 'output_value'
  省略可能なパラメータです。メールを送信し、その結果は送信元のクライアント セッションには返しません。既定値は FALSE です。これは、SQL Server のクライアント セッションで結果を受け取ることを示します。

• [ @no_header=] 'header_value'
  省略可能なパラメータです。クエリの結果をメールで送信しますが、列ヘッダー情報は送信しません。既定値は FALSE です。これは、列ヘッダー情報をクエリの結果と共に送信することを示します。

• [ @width=] width
  省略可能なパラメータです。クエリの出力テキスト行の幅を設定します。このパラメータは、isql ユーティリティの /w パラメータと同じです。長い出力行を生成するクエリの場合は、出力行が途中で切れることなく送信されるよう、attach_results と共に width を使用してください。行幅の既定値は 80 バイトです。

• [ @separator=] 'separator'
  結果セットの各列の列の区切り文字を指定します。既定では、列の区切り文字は空白文字です。列の区切り文字を使用すると、表計算などのアプリケーションで結果セットを解析するのが簡単になります。たとえば、コンマ区切り値のファイルを送る場合には、attach_results と共に separator を使用してください。

• [ @echo_error=] 'echo_value'
  TRUE の場合、SQL Mail ではクエリ実行中に発生したサーバー メッセージや DB-Library エラーがすべてキャプチャされ、これらはエラー ログに書き込まれるのでなくメール メッセージに追加されます。メール メッセージには、返された行数または影響を受けた行数も追加されます。

  注
  echo_error が TRUE の場合、xp_sendmail では、DB-Library のエラーやメッセージが生成されたり、クエリで結果が返されなかったとしても、メールが正常に送信されればステータス 0 (成功) が返されます。

• [ @set_user=] 'user'
  クエリを実行するセキュリティのコンテキストを指定します。user を指定しない場合は、xp_sendmail を実行しているユーザーのセキュリティ コンテキストが使用されます。

• [ @dbuse=] 'database'
  クエリを実行するデータベースのコンテキストを指定します。既定値は NULL です。これは、ユーザーが既定のデータベースで実行することを示します。

リターン コードの値

0 (成功) または 1 (失敗)

結果セット

成功した場合、xp_sendmail ではメッセージが返されます。

説明

SQL Mail セッションは、xp_sendmail の実行前に開始する必要があります。セッションは自動的に、または xp_startmail で起動できます。SQL Mail のセッションを自動的に設定する方法の詳細については、「拡張 MAPI メール プロファイルの構成」を参照してください。1 つの SQL Mail セッションで SQL Server インスタンスのすべてのユーザーがサポートされますが、メッセージを送信できるのは一度に 1 ユーザーだけです。他のユーザーがメールを送信しようとすると、最初のユーザーのメッセージが送信されるまで自動的に待機することになります。

query を指定すると、xp_sendmail はクライアントとして SQL Server にログインし、指定したクエリを実行します。SQL Mail から SQL Server へは独立した接続が行われ、xp_sendmail を実行した元のクライアント接続と同じ接続が共有されることはありません。

注
query は、xp_sendmail を実行したクライアント接続が保持するロックによってブロックされることがあります。たとえば、トランザクション内でテーブルを更新し、更新された行情報を選択する更新トリガを作成した場合、query パラメータで同じ行を指定していると、最初のクライアント接続が保持している行の排他ロックによって SQL Mail 接続がブロックされます。

xp_sendmail は SQL Server のセキュリティ コンテキストで実行されます。xp_sendmail の有効なユーザーは、管理者のセキュリティ コンテキストでメール メッセージの添付ファイルにアクセスできます。システム管理者以外のユーザーが xp_sendmail にアクセスする場合、添付ファイルへ不用意にアクセスされるのを防ぐために、システム管理者は xp_sendmail を呼び出すストアド プロシージャを作成し、そのストアド プロシージャで必要な機能だけを提供して attachments パラメータを公開しないようにできます。このストアド プロシージャは、master データベース内で定義する必要があります。ストアド プロシージャを作成したら、システム管理者はユーザーに対して、基になる xp_sendmail プロシージャの権限を与えずに、作成したストアド プロシージャの権限だけを与えます。

xp_sendmail では、指定した受信者に、メッセージとクエリ結果セットまたは添付ファイルが送信されます。query パラメータにはバインドされた接続が使用されます。SQL Mail で行われる query 接続は、xp_sendmail 要求を実行したクライアントが保持するロックによってブロックされることはありません。これにより、xp_sendmail をトリガ内部から簡単に使用できます。ただし、inserted および deleted 論理テーブルはトリガ内部でのみ使用できるため、query ステートメントでこれらのテーブルは参照できません。

注
MSSQLServer サービスの権限ではアクセスできないファイル共有上にポスト オフィスやアドレス帳がある場合、xp_sendmail を実行しようとするとアクセス違反となります。

xp_sendmail は、xml データ型を完全にはサポートしていません。xml データ型を使用するクエリは、その形式が不適切に設定される可能性があります。xml データを含む電子メールを送信する場合は、データベース メール を使用してください。

権限

sysadmin 固定サーバー ロールのメンバシップが必要です。EXECUTE 権限は他のユーザーに与えることもできます。ただしセキュリティ上の理由から、このストアド プロシージャの実行権限は、sysadmin 固定サーバー ロールのメンバだけに制限することをお勧めします。

例

A. メッセージを 1 人の受信者に送信する

次の例では、ユーザー Dan Wilson (電子メールは danw) に、master データベースがいっぱいになったことを知らせるメッセージを送信します。

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @message=N'The master database is full.' ;

B. 複数の受信者にメッセージを送信する

次の例では、ユーザー Dan Wilson と Ashvini Sharma (電子メールは ashvinis) にメッセージを送信し、メッセージのコピーを Peter Connelly (電子メールは peterc) に送信します。また、この例ではメッセージの件名の行も指定します。

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. 結果を送信する

次の例では、sp_configure の結果を Dan Wilson に送信します。

EXEC master.dbo.xp_sendmail 
    @recipients=N'danw@Adventure-Works.com',
    @query = N'EXEC sp_configure' ;
GO

D. 結果を添付ファイルとして送信する

次の例では、クエリ SELECT * FROM INFORMATION_SCHEMA.TABLES の結果をテキスト添付ファイルとして Dan Wilson に送信します。この例では添付ファイルの前に表示されるメールの件名の行とメッセージも指定します。また、出力行が切れるのを防ぐために @width パラメータを使用します。

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. 7,990 バイトより長いメッセージを送信する

次の例では、7,990 バイトより長いメッセージを送信します。message は、すべてのストアド プロシージャのパラメータと同様、行のオーバーヘッドが少ない VARCHAR 型の長さに制限されています。したがって、この例では長いメッセージを単一のテキスト列から成るグローバル一時テーブルに書き込み、その後、@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 ;

関連項目

参照

sp_processmail (Transact-SQL)

システム ストアド プロシージャ (Transact-SQL)

xp_deletemail (Transact-SQL)

xp_findnextmsg (Transact-SQL)

xp_readmail (Transact-SQL)

xp_startmail (Transact-SQL)

xp_stopmail (Transact-SQL)

sp_send_dbmail (Transact-SQL)