電子メール送信アダプタの使用法
ここでは、電子メール送信アダプタ (EnsLib.EMail.OutboundAdapterOpens in a new tab) の動作、およびプロダクションでのこのアダプタの使用法について説明します。
このドキュメントに記載されていない設定は、"すべてのプロダクションに含まれる設定" を参照してください。
全般的な動作
プロダクション内で、送信アダプタは、ユーザが作成および構成するビジネス・オペレーションに関連付けられます。このビジネス・オペレーションはプロダクション内からメッセージを受信し、メッセージ・タイプを調べ、適切なメソッドを実行します。このメソッドは、通常、関連するアダプタのメソッドを実行します。
電子メール送信アダプタ (EnsLib.EMail.OutboundAdapterOpens in a new tab) には、以下のような項目の指定に使用する設定が用意されています。
-
接続する SMTP サーバ、およびそのサーバに対して必要なログイン情報 (ある場合)
-
電子メール送信元のデフォルト・アドレス (From: ヘッダ)
-
ハードコードされた受信者の他に、アダプタが送信するメッセージに追加する受信者
このアダプタは、以下の 3 つのアクションを行うメソッドを提供します。
-
To: リストへの受信者の追加
-
Cc: リストへの受信者の追加
-
メッセージの送信
アダプタを使用するビジネス・オペレーションの作成
EnsLib.EMail.OutBoundAdapter を使用するビジネス・オペレーションを作成するために、新しいビジネス・オペレーション・クラスを作成します。後で、そのクラスをプロダクションに追加して構成します。
存在しなければ、該当するメッセージ・クラスを作成する必要もあります。"メッセージの定義" を参照してください。
ビジネス・オペレーション・クラスの基本要件を以下に列挙します。
-
ビジネス・オペレーション・クラスは、Ens.BusinessOperationOpens in a new tab を拡張するものでなければなりません。
-
クラスの ADAPTER パラメータは EnsLib.EMail.OutboundAdapterOpens in a new tab である必要があります。
-
クラスの INVOCATION パラメータは、使用する呼び出しスタイルを指定する必要があります。以下のいずれかを使用します。
-
Queue は、メッセージが 1 つのバックグラウンド・ジョブ内で作成され、元のジョブが解放された段階でキューに配置されます。その後、メッセージが処理された段階で、別のバックグラウンド・ジョブがそのタスクに割り当てられます。これは最も一般的な設定です。
-
InProc は、メッセージが、作成されたジョブと同じジョブで生成、送信、および配信されることを意味します。このジョブは、メッセージが対象に配信されるまで送信者のプールに解放されません。これは特殊なケースのみに該当します。
-
-
クラスでは、少なくとも 1 つのエントリを含むメッセージ・マップを定義します。メッセージ・マップは、以下の構造を持つ XData ブロック・エントリです。
XData MessageMap { <MapItems> <MapItem MessageType="messageclass"> <Method>methodname</Method> </MapItem> ... </MapItems> }
-
クラスでは、メッセージ・マップ内で名前が付けられたすべてのメソッドを定義します。これらのメソッドは、メッセージ・ハンドラと呼ばれます。各メッセージ・ハンドラは、以下のシグニチャを持っている必要があります。
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
ここで、Sample はメソッド名、RequestClass は要求メッセージ・クラスの名前、ResponseClass は応答メッセージ・クラスの名前です。通常、これらのメソッドは、ビジネス・オペレーションの Adapter プロパティのプロパティおよびメソッドを参照します。
-
その他のオプションと一般情報は、"ビジネス・オペレーション・クラスの定義" を参照してください。
以下の例は、必要となる一般的な構造を示しています。
Class EEMA.NewOperation1 Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.EMail.OutboundAdapter";
Parameter INVOCATION = "Queue";
Method SampleCall(pRequest As Ens.Request,
Output pResponse As Ens.Response) As %Status
{
Quit $$$ERROR($$$NotImplemented)
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="Ens.Request">
<Method>SampleCall</Method>
</MapItem>
</MapItems>
}
}
メッセージ・ハンドラ・メソッドの作成
EnsLib.EMail.OutboundAdapterOpens in a new tab で使用するビジネス・オペレーション・クラスを作成する場合の最大のタスクは、通常、このアダプタで使用するメッセージ・ハンドラ、つまり、プロダクション・メッセージを受信して SMTP サーバを介して電子メール・メッセージを送信するメソッドの記述です。
各メッセージ・ハンドラ・メソッドは、以下のシグニチャを持っている必要があります。
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
ここで、Sample はメソッド名、RequestClass は要求メッセージ・クラスの名前、ResponseClass は応答メッセージ・クラスの名前です。
通常、このメソッドは以下の操作を実行します。
-
受信要求メッセージを調べます。
-
送信する電子メール・メッセージを作成します。詳細は、"電子メール・メッセージの作成" を参照してください。
-
任意で、ビジネス・オペレーションの Adapter プロパティの AddRecipients()、AddCcRecipients()、および AddBccRecipients() メソッドを呼び出します。これらのメソッドは、電子メール・メッセージの送信時に、To: ヘッダ、Cc: ヘッダ、および Bcc: ヘッダに電子メール・アドレスを追加します。これらのメソッドについては、後で説明します。
-
ビジネス・オペレーションの Adapter プロパティの SendMail() メソッドを呼び出します。
Set tSc=..Adapter.SendMail(email,.pf)
このメソッドについては、後で説明します。
-
応答を調べます。
-
応答内の情報を使用して、応答メッセージ (Ens.ResponseOpens in a new tab またはサブクラスのインスタンス) を作成します。メソッドは出力としてこのメッセージを返します。
メッセージ・クラスの定義方法は、"メッセージの定義" を参照してください。
-
必ず出力引数 (pOutput) を設定します。通常、応答メッセージと同じように設定します。この手順は必須です。
-
適切なステータスを返します。この手順は必須です。
使用可能なメソッド
このアダプタは、以下のメソッドを提供します。
Method SendMail(pMailMessage As %Net.MailMessage,
Output pFailedRecipients As %ListOfDataTypes) As %Status
電子メール・メッセージを指定すると、このメソッドは、構成された SMTP サーバを使用して電子メール・メッセージを送信します。SMTP サーバによって失敗した受信者のリストが返されると、このメソッドは、出力として失敗した受信者のリストを返します。
Method AddRecipients(pMailMessage As %Net.MailMessage,
pRecipients As %String)
電子メール・メッセージを指定すると、このメソッドは、メッセージの To: ヘッダに、リストされた電子メール・アドレスを追加します。
Method AddCcRecipients(pMailMessage As %Net.MailMessage,
pRecipients As %String)
電子メール・メッセージを指定すると、このメソッドは、メッセージの Cc: ヘッダに、リストされた電子メール・アドレスを追加します。
Method AddBccRecipients(pMailMessage As %Net.MailMessage,
pRecipients As %String)
電子メール・メッセージを指定すると、このメソッドは、メッセージの Bcc: ヘッダに、リストされた電子メール・アドレスを追加します。電子メールを送信する際は、To: ヘッダまたは Cc: ヘッダに少なくとも 1 つのアドレスを指定する必要があります。
Method ContinueAfterBadSendSet(%val As %Integer) as %Status
%val が真の場合は、1 人以上の受信者のアドレスが無効なときに、アダプタはメッセージの送信を続行します。デフォルトは真です。
例
メソッドは以下のようになります。
Method SendMultipartEmailMessage(pRequest As EEMA.MultipartEmailMsg,
Output pResponse As Ens.Response) As %Status
{
Set part1=##class(%Net.MailMessage).%New()
Do part1.TextData.Write(pRequest.Message1)
Set part2=##class(%Net.MailMessage).%New()
Do part2.TextData.Write(pRequest.Message2)
Set part3=##class(%Net.MailMessage).%New()
Do part3.TextData.Write(pRequest.Message3)
Set email=##class(%Net.MailMessage).%New()
Set email.Subject=pRequest.Subject
Set email.IsMultiPart=1
Do email.Parts.SetAt(part1,1)
Do email.Parts.SetAt(part2,2)
Do email.Parts.SetAt(part3,3)
Set tSc=..Adapter.SendMail(email,.pf)
Set pResponse=##class(EEMA.EmailFailedRecipients).%New()
Set pResponse.FailedRecipients=pf
if pf.Count()'=""
{
set count=pf.Count()
for i=1:1:count
{
$$$TRACE("Failed recipient:"_pf.GetAt(i))
}
}
Quit tSc
}
電子メール・メッセージの作成については、次の節を参照してください。
電子メール・メッセージの作成
メッセージには 1 つまたは複数のパートを含めることができます。各パートにはコンテンツが含まれ、ヘッダを含めることができます。メッセージ自体にもヘッダがあります。以下の節で、次のトピックについて説明します。
使用している SMTP サーバの要件を理解しておく必要があります。例えば、一部の SMTP サーバでは Subject: ヘッダを含める必要があります。同様に、一部の SMTP サーバでは任意の From: ヘッダを許可しない場合があります。
電子メール・メッセージの作成
電子メール・メッセージを作成するには、以下の操作を行います。
-
%Net.MailMessageOpens in a new tab のインスタンスを作成します。
Tip:%New() への引数として文字セットを指定できます。文字セットを指定した場合は、メッセージに Charset プロパティが設定されます。
文字セットおよび変換テーブルの詳細は、"変換テーブル" を参照してください。
-
インスタンスの To プロパティ、From プロパティ、および Subject プロパティを設定します。これらのプロパティは必須です。
-
To — このメッセージの送信先となる電子メール・アドレスのリスト。このプロパティは、標準の InterSystems IRIS リストです。これを使用するには、標準のリスト・メソッドである Insert()、GetAt()、RemoveAt()、Count()、および Clear() を使用します。
-
From — このメッセージの送信元の電子メール・アドレス。
-
Subject — メッセージの件名。
-
-
必要に応じて、Date、Cc、Bcc およびその他のプロパティを設定します。詳細は、"基本的なヘッダ" を参照してください。
-
シングルパート・メッセージを作成する場合、"メッセージ・パートのコンテンツおよびヘッダの指定" で説明されているようにコンテンツおよびヘッダを指定します。
-
マルチパート・メッセージを作成する場合は、以下の操作を行います。
-
IsMultiPart プロパティを 1 に設定します。
-
MultiPartType プロパティを、"related"、"alternative"、または "mixed" のいずれかに設定します。
-
メッセージに含まれる各パートに対して、%Net.MailMessagePartOpens in a new tab のインスタンスを作成します。次に、"メッセージ・パートのコンテンツおよびヘッダの指定" で説明されているようにコンテンツおよびヘッダを指定します。
-
親電子メール・メッセージに対して Parts プロパティを設定します。これは配列です。この配列に、各子メッセージ・パートを挿入します。
-
メッセージ・パートのコンテンツおよびヘッダの指定
-
メッセージがプレーン・テキストでない場合、以下のプロパティを設定して、作成するメッセージの種類を指定します。
-
これが HTML メッセージの場合は、IsHTML プロパティを 1 に設定します。
-
これがバイナリ・メッセージの場合は、IsBinary プロパティを 1 に設定します。
-
-
メッセージとそのヘッダの文字セットを指定する場合は、必要に応じて、Charset プロパティを設定します。
Important:メッセージのコンテンツを追加する前に文字セットを指定することが重要です。
文字セットおよび変換テーブルの詳細は、"変換テーブル" を参照してください。
-
メッセージのコンテンツを追加します。
-
プレーン・テキストまたは HTML の場合は、TextData プロパティを使用します。これは %FileCharacterStreamOpens in a new tab のインスタンスです。このストリームの TranslateTable プロパティを指定する必要はありません。電子メール・メッセージの文字セットを指定すると自動的に発生します。
システムは、自動的に、文字エンコーディングを以前のステップで指定されたエンコーディングに変換します。
-
バイナリ・データの場合は、BinaryData プロパティを使用します。これは %FileBinaryStreamOpens in a new tab のインスタンスです。
%FileCharacterStreamOpens in a new tab および %FileBinaryStreamOpens in a new tab は非推奨になっていますが、このような使用法は引き続きサポートされています。このユース・ケースで別のストリーム・クラスに置き換えることはお勧めできません。
Tip:ストリームの Filename プロパティを指定するときは、ユーザが書き込み権限を持っているディレクトリを使用してください。
これらのプロパティを操作するには、標準ストリーム・メソッドの Write()、WriteLine()、Read()、ReadLine()、Rewind()、MoveToEnd()、および Clear() を使用します。また、ストリームの Size プロパティを使用して、メッセージ・コンテンツのサイズを指定することもできます。
-
メッセージ・ヘッダの指定
前述したとおり、メッセージ自体およびメッセージの各パートの両方には、一連のヘッダがあります。
%Net.MailMessageOpens in a new tab クラスおよび %Net.MailMessagePartOpens in a new tab クラスは、最も一般的に使用されるヘッダに簡単にアクセスできるようにするプロパティを提供しますが、必要なヘッダを追加することができます。この節では、すべてのヘッダに関する情報を提供すると共に、カスタム・ヘッダの作成方法についても説明します。
指定されたメッセージ・パートのヘッダは、そのパートの Charset プロパティで指定された文字セットで記述されます。
基本的なヘッダ
以下のプロパティ (%Net.MailMessageOpens in a new tab のみ) を設定し、メッセージ自体の最も一般的に使用されるヘッダを指定します。
-
To — (必須) このメッセージの送信先となる電子メール・アドレスのリスト。このプロパティは、標準の InterSystems IRIS リストです。これを使用するには、標準のリスト・メソッドである Insert()、GetAt()、RemoveAt()、Count()、および Clear() を使用します。
-
From — (必須) このメッセージの送信元の電子メール・アドレス。
-
Date — このメッセージの日付。
-
Subject — このメッセージの件名を含む文字列。
-
Sender — メッセージの実際の送信者。
-
Cc — このメッセージの送信先となるカーボン・コピー・アドレスのリスト。
-
Bcc — このメッセージの送信先となるブラインド・カーボン・コピー・アドレスのリスト。
使用している SMTP サーバの要件を理解しておく必要があります。例えば、一部の SMTP サーバでは Subject: ヘッダを含める必要があります。同様に、一部の SMTP サーバでは任意の From: ヘッダを許可しない場合があります。
Content-Type ヘッダ
メッセージを送信する場合、メッセージおよび各メッセージ・パートの Content-Type ヘッダは、自動的に以下のように設定されます。
-
メッセージがプレーン・テキストの場合 (IsHTML が 0 で IsBinary が 0 の場合)、Content-Type ヘッダは "text/plain" に設定されます。
-
メッセージが HTML の場合 (IsHTML が 1 で IsBinary が 0 の場合)、Content-Type ヘッダは "text/html" に設定されます。
-
メッセージがバイナリの場合 (IsBinary が 1 の場合)、Content-Type ヘッダは "application/octet-stream" に設定されます。
-
メッセージがマルチパートの場合、Content-Type ヘッダは MultiPartType プロパティの値に対して適切に設定されます。
%Net.MailMessageOpens in a new tab および %Net.MailMessagePartOpens in a new tab は共に、ContentType プロパティを提供します。このプロパティは、Content-Type ヘッダへのアクセスを提供します。
Content-Transfer-Encoding ヘッダ
%Net.MailMessageOpens in a new tab および %Net.MailMessagePartOpens in a new tab は共に、ContentTransferEncoding プロパティを提供します。このプロパティは、メッセージまたはメッセージ・パートの Content-Transfer-Encoding ヘッダを簡単に指定する方法を提供します。
このプロパティは、"base64"、"quoted-printable"、"7bit"、"8bit" のいずれかです。
デフォルトは以下のとおりです。
-
バイナリのメッセージまたはメッセージ・パートには、"base64" を使用します。
-
テキストのメッセージまたはメッセージ・パートには、"quoted-printable" を使用します。
カスタム・ヘッダ
%Net.MailMessageOpens in a new tab および %Net.MailMessagePartOpens in a new tab の両方を使用して、Headers プロパティにアクセスすることにより、カスタム・ヘッダを設定または取得できます。このプロパティは、以下の構造を持つ配列です。
配列キー | 配列の値 |
---|---|
"Priority" など、ヘッダの名前 | ヘッダの値 |
このプロパティを使用して、優先順位などの追加のヘッダを含めます。以下に例を示します。
Do msg.Headers.SetAt("Urgent","Priority")
アタッチメントの追加
電子メールのメッセージまたはメッセージ・パートにアタッチメントを追加できます。そのためには、%Net.MailMessagePartOpens in a new tab または %Net.MailMessageOpens in a new tab の以下のメソッドを使用します。
これらの各メソッドは、元のメッセージ (またはメッセージ・パート) の Parts 配列にアタッチメントを追加し、自動的に IsMultiPart プロパティを 1 に設定します。
method AttachFile(Dir As %String,
File As %String,
isBinary As %Boolean = 1,
charset As %String = "",
ByRef count As %Integer) as %Status
指定されたファイルを電子メール・メッセージに添付します。デフォルトでは、ファイルはバイナリ・アタッチメントとして送信されますが、代わりにテキストとして指定することができます。また、このファイルがテキストの場合、ファイルが使用する文字セットを指定することもできます。(文字セットおよび変換テーブルの詳細は、"変換テーブル" を参照してください。)
具体的には、このメソッドは %Net.MailMessagePartOpens in a new tab のインスタンスを作成し、BinaryData または TextData プロパティ内のファイルのコンテンツを適切に配置し、Charset プロパティおよび TextData.TranslateTable プロパティを必要に応じて設定します。このメソッドは、Parts 配列内のこの新しいメッセージ・パートの位置を示す整数を、参照渡しで返します。
このメソッドは、メッセージまたはメッセージ・パートの Dir プロパティおよび FileName プロパティも設定します。
method AttachNewMessage() as %Net.MailMessagePart
%Net.MailMessageOpens in a new tab の新しいインスタンスを作成し、メッセージに追加して、新しく修正された親のメッセージまたはメッセージ・パートを返します。
method AttachEmail(mailmsg As %Net.MailMessage)
電子メール・メッセージ (%Net.MailMessageOpens in a new tab のインスタンス) を指定すると、このメソッドは、それをメッセージに追加します。
このメソッドは、ContentType を "message/rfc822" に設定します。この場合、他のアタッチメントを追加することはできません。
例については、%Net.MailMessagePartOpens in a new tab のクラス参照を参照してください。
例
以下に例を示します。
ClassMethod CreateTextMessage() As %Net.MailMessage
{
Set msg = ##class(%Net.MailMessage).%New()
set msg.From = "test@test.com"
Do msg.To.Insert("xxx@xxx.com")
Do msg.Cc.Insert("yyy@yyy.com")
Do msg.Bcc.Insert("zzz@zzz.com")
Set msg.Subject="subject line here"
Set msg.IsBinary=0
Set msg.IsHTML=0
Do msg.TextData.Write("This is the message.")
Quit msg
}
例
この節では、文字列コンテンツを含むシングルパートまたはマルチパートの電子メール・メッセージを送信する例を示します。プロダクション・システムでは、文字列の代わりにストリームを使用する場合もあります。ただし、この例では文字列を使用するので、プロダクション・テスト・ページを使用して簡単にテストできます。
まず、シングルパート・メッセージの要求メッセージ・クラスは、以下のようになります。
Class EEMA.SimpleMsg Extends Ens.Request
{
Property Subject As %String(MAXLEN = 100);
Property Message As %String(MAXLEN = 5000);
}
次は、マルチパート・メッセージの要求メッセージ・クラスです。このクラスには、3 パートのメッセージを含めることができます。
Class EEMA.MultipartMsg Extends Ens.Request
{
Property Subject As %String(MAXLEN = 100);
Property Part1 As %String(MAXLEN = 5000);
Property Part2 As %String(MAXLEN = 5000);
Property Part3 As %String(MAXLEN = 5000);
}
以下のビジネス・オペレーションは、これらのメッセージのいずれかを受け取り、適切な電子メール・メッセージを作成して、構成された SMTP サーバを介して送信します。
Class EEMA.EmailOperation Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.EMail.OutboundAdapter";
Parameter INVOCATION = "Queue";
Method SendSimpleMessage(pRequest As EEMA.SimpleMsg,
Output pResponse As Ens.Response) As %Status
{
Set email=##class(%Net.MailMessage).%New()
//Get info from pReq
Do email.TextData.Write(pRequest.Message)
Set email.Subject=pRequest.Subject
//simple case--do not check for failed recipients
Set tSc=..Adapter.SendMail(email)
//send an empty response message after message is sent
Set pResponse=##class(Ens.Response).%New()
;Quit tSc
}
Method SendMultipartEmailMessage(pRequest As EEMA.MultipartMsg,
Output pResponse As Ens.Response) As %Status
{
Set part1=##class(%Net.MailMessage).%New()
Do part1.TextData.Write(pRequest.Part1)
Set part2=##class(%Net.MailMessage).%New()
Do part2.TextData.Write(pRequest.Part2)
Set part3=##class(%Net.MailMessage).%New()
Do part3.TextData.Write(pRequest.Part3)
Set email=##class(%Net.MailMessage).%New()
Set email.Subject=pRequest.Subject
Set email.IsMultiPart=1
Do email.Parts.SetAt(part1,1)
Do email.Parts.SetAt(part2,2)
Do email.Parts.SetAt(part3,3)
//simple case--do not check for failed recipients
Set tSc=..Adapter.SendMail(email)
//send an empty response message after message is sent
Set pResponse=##class(Ens.Response).%New()
Quit tSc
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="EEMA.SimpleMsg">
<Method>SendSimpleMessage</Method>
</MapItem>
<MapItem MessageType="EEMA.MultipartMsg">
<Method>SendMultipartEmailMessage</Method>
</MapItem>
</MapItems>
}
}
ビジネス・オペレーションの追加と構成
ビジネス・オペレーションをプロダクションに追加するには、管理ポータルを使用して以下の操作を行います。
-
カスタム・ビジネス・オペレーション・クラスのインスタンスをプロダクションに追加します。
-
ビジネス・オペレーションを有効化します。
-
プロダクションを実行します。
SMTP サーバへのログイン方法の指定
使用する SMTP サーバおよびそれに関連するログイン資格情報を指定するには、EnsLib.EMail.OutboundAdapterOpens in a new tab の以下の設定に対して値を指定します。
例えば、以下のような値を使用できます。
設定 | 値 |
---|---|
SMTPサーバ | smtp.hotpop.com |
SMTPポート | 25 |
Credentials | hotpop |
この例にある hotpop は、ユーザ名 isctest@hotpop.com とこれに対応するパスワードから成るプロダクション認証情報 の ID です。
追加の電子メール・アドレスの指定
EnsLib.EMail.OutboundAdapterOpens in a new tab の以下の設定を使用して、このアダプタから送信される電子メール・メッセージの電子メール・アドレスを指定できます。
ここに記載されていない設定については、"プロダクションの構成" を参照してください。