Skip to main content

POP3 を介した電子メールの取得

ここでは、%Net.POP3Opens in a new tab クラスを使用して、電子メール・メッセージを取得する方法について説明します。

概要

必要な権限があり、メール・サーバが稼動している場合、POP3 プロトコルを使用して、メール・サーバから電子メール・メッセージをダウンロードし、処理することができます。一般に、POP3 を介してメール・サーバと通信するには、ログインし、メールボックスに影響を与える一連のアクションを実行し、変更をコミットまたはロールバックします。InterSystems IRIS 内でこれを行うには、以下を実行します。

  1. %Net.POP3Opens in a new tab のインスタンスを作成します。このオブジェクトは、使用するメール・サーバを記述します。

  2. オプションで、%Net.POP3Opens in a new tab のインスタンスの以下のプロパティを指定します。

    • port — 使用するポートを指定します。既定値は 110 です。

    • timeout — 読み取りタイムアウトを秒単位で指定します。既定値は 30 秒です。

    • StoreAttachToFile — メッセージを読み取る際に、各添付をファイルに保存するかどうかを指定します (メッセージが content-disposition; attachment ヘッダを含んでいる場合)。既定値は False です。

      この設定は、AttachDir も設定しないと、何も実行しないことに注意してください。

    • StoreInlineToFile — メッセージを読み取る際に、各インライン添付をファイルに保存するかどうかを指定します (メッセージが content-disposition; inline ヘッダを含んでいる場合)。既定値は False です。

      この設定は、AttachDir も設定しないと、何も実行しないことに注意してください。

    • AttachDir — 添付を保存するディレクトリを指定します。既定値はありません。ディレクトリの名前は、オペレーティング・システムに応じて適切に、スラッシュ (/) またはバックスラッシュ (\) で終わるようにします。また、これが既に存在するディレクトリで、ユーザがこれに対するアクセス権を持っていることを確認してください。

    • IgnoreInvalidBase64Chars — Base-64 デコード中に検出された無効な文字を無視するかどうかを指定します。既定値は false です (無効な文字ではエラーが発生します)。RFC 2045Opens in a new tab では、Base-64 デコード中に予期しない文字を無視するか、エラーを発生させるかは曖昧です。

  3. サーバへの SSL/TLS 接続を使用するには

    1. SSLConfiguration プロパティを使用する有効化した SSL/TLS 構成の名前に設定します。

      SSL/TLS 構成の作成と管理の詳細は、インターシステムズの "TLS ガイド" を参照してください。SSL/TLS 構成には、[構成名] と呼ばれるオプションが含まれています。これは、この設定で使用する文字列です。

    2. UseSTARTTLS プロパティを 0 か 1 に設定します。

      ほとんどの場合、0 の値を使用します。通常の TCP ソケットでサーバのやり取りが開始した後、通常のソケットとして同じポートの TLS に切り替わる場合、1 の値を使用します。詳細は、"RFC 2595Opens in a new tab" を参照してください。

      UseSTATRTLS を 1 に設定している場合は、既定のポート 995 ではなく、ポート 110 にサーバを接続します。

    3. 必要に応じて、SSLCheckServerIdentity プロパティを 1 に設定します。これは、証明書のホスト・サーバ名を確認する場合に設定します。

  4. インスタンスの Connect() メソッドを呼び出します。このメソッドは、3 つの引数を以下の順番で取ります。

    1. POP3 サーバの名前

    2. ユーザ名

    3. パスワード

  5. インスタンスのメソッドを使用して、メールボックスを調べ、メッセージを取得し、メッセージを削除します。以下のセクションで詳細を説明します。

  6. オプションで、接続がタイムアウトするのを防ぐため、%Net.POP3Opens in a new tab インスタンスの Ping() メソッドを呼び出します。

  7. オプションで、削除するようメッセージにマーク付けしたものの、やはり削除しないことにした場合は、%Net.POP3Opens in a new tab インスタンスの RollbackDeletes() メソッドを呼び出します。

  8. メールボックスへの変更が完了したら、以下のメソッドのいずれかを呼び出します。

    • QuitAndCommit() — 変更をコミットし、メール・サーバからログアウトします。

    • QuitAndRollback() — 変更をロールバックし、メール・サーバからログアウトします。

これらの各メソッドはステータスを返すので、続行する前にそれを確認する必要があります。完全なメソッドのシグニチャについては、%Net.POP3Opens in a new tab のクラス・リファレンスも参照してください。

XOAUTH2 認証の有効化

%Net.POP3Opens in a new tab では、認証方法として XOAUTH2 をサポートしています。

%Net.POP3Opens in a new tab で XOAUTH2 を使用するには、アクセス・トークンをパラメータとして %Net.POP3.Connect()Opens in a new tab に渡します。このメソッドは、アクセス・トークンを渡されると、パスワードが提供されたかどうかに関係なく、XOAUTH2 を使用しようとします。XOAUTH2 の使用を望まない場合は、アクセス・トークン・パラメータを渡さないように注意する必要があります。

接続例

以下の例は、このコンテンツ執筆時点で使用可能な 2 つの異なる無料 POP3 サービスを使用しています。これらのサービスの選択は、特に推奨を意味しているわけではありません。また、例で示しているのは、実際のパスワードではありません。

例 1 ： HotPOPAsPOP3()

以下のメソッドがこの目的で既に設定されているアカウントを使用して、HotPOP POP3 サーバにログインします。

ClassMethod HotPOPAsPOP3() As %Net.POP3
{
  Set server=##class(%Net.POP3).%New()
  
  //HotPOP POP3 server uses the default port
  //but let's set it anyway
  Set server.port=110

  //just in case we plan to fetch any messages
  //that have attachments
  Set server.StoreAttachToFile=1
  Set server.StoreInlineToFile=1
  Set server.AttachDir="c:\DOWNLOADS\"

  Set servername="pop.hotpop.com"
  Set user="isctest@hotpop.com"
  Set pass="123pass"
  
  Set status=server.Connect(servername,user,pass)
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status) 
    Quit $$$NULLOREF
  }
  Quit server
}

このメソッドは、%Net.POP3Opens in a new tab サーバ・インスタンスを返します。このトピックで後述する例の多くは、%Net.POP3Opens in a new tab インスタンスを引数として受け入れます。

例 2 ： YPOPsAsPOP3()

以下のメソッドも、%Net.POP3Opens in a new tab サーバ・インスタンスを返します。この場合、Yahoo 電子メール・アカウントへの SMTP および POP3 アクセスを提供するクライアント・ソフトウェアである YPOP を使用しています。これは、この目的で既に設定されているテスト・アカウントを使用します。

ClassMethod YPOPsAsPOP3() As %Net.POP3
{
  Set server=##class(%Net.POP3).%New()
  
  //YPOPs uses the default port 
  //but let's set it anyway
  Set server.port=110

  //just in case we plan to fetch any messages
  //that have attachments
  Set server.StoreAttachToFile=1
  Set server.StoreInlineToFile=1
  Set server.AttachDir="c:\DOWNLOADS\"
  
  //local host acts as the server
  Set servername="127.0.0.1"
  //YPOPs works with a Yahoo email account
  Set user="isc.test@yahoo.com"
  Set pass="123pass"
  
  Set status=server.Connect(servername,user,pass)
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status) 
    Quit $$$NULLOREF
  }
  Quit server
}

メールボックスに関する情報の取得

POP3 サーバに接続している間、ユーザ・アカウントにログインし、そのユーザ・アカウントのメールボックスにアクセスできます。以下のメソッドを使用して、メールボックスに何が含まれているのかを検索します。

GetMailBoxStatus()

メールボックス内のメッセージ数およびメールボックスが使用するバイト数を、参照によって返します。

GetMessageUIDArray()

最初の引数として空の文字列が指定されている場合、このメソッドは、メールボックス内のメッセージについての情報の配列を、参照によって返します (現在削除するようマーク付けされているものを除く)。この配列の各要素には、1 つのメッセージについての以下の情報が含まれています。

配列キー 配列項目
現在の状態でのメールボックス内のメッセージの番号。最初のメッセージが 1 番で、以降順次番号が割り当てられます。

指定したメッセージのメッセージ番号がすべてのセッションで同じであることは保証されません。

 すべてのセッションで使用できる、このメッセージの永久の識別子である、一意のメッセージ識別子 (UID)。

UID は、各メールボックスに対して一意です。
GetSizeOfMessages()

最初の引数として空の文字列が指定されている場合、このメソッドは、メールボックス内のメッセージについての情報の配列を、参照によって返します (現在削除するようマーク付けされているものを除く)。この配列の各要素には、1 つのメッセージについての以下の情報が含まれています。

配列キー 配列項目
現在の状態でのメールボックス内のメッセージの番号。 このメッセージのサイズ (単位はバイト)。

これらの各メソッドはステータスを返すので、続行する前にそれを確認する必要があります。これらのメソッドの詳細は、"その他のメッセージ取得メソッド" も参照してください。

例 ： ShowMailbox()

例えば、以下のメソッドは、現在アクセスしているメールボックスについての情報を記述します。

ClassMethod ShowMailbox(server as %Net.POP3) 
{
    Set status=server.GetMailBoxStatus(.count,.size)
    If $$$ISERR(status) {
       Do $System.Status.DisplayError(status) 
       Quit 
    }
    Write "Mailbox information *****",!
    Write "Number of messages in mailbox: ",count,!
    Write "Size of messages: ",size,!

    Set status=server.GetMessageUIDArray(,.uids)
    Set status=server.GetSizeOfMessages(,.sizes)
    
    //iterate through messages, get info, and write it
    For i=1:1:count {
        Set uid=uids.GetAt(i)
        Set size=sizes.GetAt(i)
        Write "Msg number:", i,"   UID:",uid, "   size:",size,!
    }

}

このメソッドは、以下のような出力を生成します。

Mailbox information *****
Number of messages in mailbox: 4
Size of messages: 18634
Msg number:1   UID:6ef78df6fd660391   size:7245
Msg number:2   UID:7410041a6faf4a87   size:5409
Msg number:3   UID:5555af7fa489e406   size:5121
Msg number:4   UID:299ad2b54c01a6be   size:859

メッセージの取得

単にメッセージを取得するには、%Net.POP3Opens in a new tab クラスの以下のメソッドのいずれかを使用します。

Fetch()

最初の引数としてメッセージ番号が指定されている場合、このメソッドは (2 番目の引数として、参照によって) そのメッセージを含む %Net.MailMessageOpens in a new tab のインスタンスを返します。

FetchMessage()

最初の引数としてメッセージ番号が指定されている場合、このメソッドは、From や To およびその他の共通ヘッダなどの情報、すべてのヘッダ (共通ヘッダを含む) を含む配列、およびメッセージ・コンテンツ自体を (参照によって) 返します。

これらの各メソッドはステータスを返すので、続行する前にそれを確認する必要があります。メッセージが現在削除するようマーク付けされている場合、これらのメソッドは、エラー・ステータスを返します。

Fetch() および FetchMessage() のメソッド・シグニチャ一覧については、"その他のメッセージ取得メソッド" も参照してください。

例 ： FetchMailbox()

以下の例は、"メールボックスに関する情報の取得" で説明されている ShowMailbox の例のバリエーションです。このメソッドは、Fetch() メソッドを使用し、各メッセージを調べ、各メッセージの件名行を記述します。

ClassMethod FetchMailbox(server As %Net.POP3)
{
  Set status=server.GetMailBoxStatus(.count,.size)
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status) 
    Quit $$$NULLOREF
  }
  Write "Mailbox information *****",!
  Write "Number of messages in mailbox: ",count,!
  Write "Size of messages: ",size,!

  Set status=server.GetMessageUIDArray(,.uids)
  Set status=server.GetSizeOfMessages(,.sizes)
  
  //iterate through messages, get info, and write it
  For i=1:1:count {
    Set uid=uids.GetAt(i)
    Set size=sizes.GetAt(i)
    Set status=server.Fetch(i,.msg)
    If $$$ISERR(status) {
      Set subj="***error***"
    } else{
      Set subj=msg.Subject
    }
    Write "Msg number:", i,"  UID:",uid, "  Size:",size
    Write "  Subject: ",subj,!
  }
}

エンコードと文字変換

電子メールのメッセージ部分には、使用されている文字セットおよび使用されている Content-Transfer-Encoding (存在する場合) の両方についての情報が含まれています。参照のため、このセクションでは、この情報の使用方法について説明します。

文字セットおよび変換テーブルの詳細は、"変換テーブル" を参照してください。

%Net.POP3Opens in a new tab は、各メッセージ部分の Content-Transfer-Encoding ヘッダを確認し、必要に応じて本文をデコードします。

その後、%Net.POP3Opens in a new tab は、各メッセージ部分の Content-Type ヘッダを確認します。これは、メッセージ部分の Charset プロパティに影響を与え、また、メッセージ部分が InterSystems IRIS 内で作成されるときに使用される変換テーブルの制御も行います。

添付の保存

Content-Disposition ヘッダにより、ファイル名を付加、あるいは付加せずに attachment を指定する場合があります。以下はその例です。

Content-Disposition: attachment; filename=genome.jpeg;

Content-Disposition ヘッダで attachment を指定した場合、ユーザの %Net.POP3Opens in a new tab インスタンスでメッセージ内のすべての添付をファイルに保存できます。この機能を有効にするには、以下を行います。

  1. %Net.POP3Opens in a new tab のインスタンスの以下のプロパティを指定します。

    • StoreAttachToFile を 1 に設定します。

    • StoreInlineToFile を 1 に設定します。

    • AttachDir に有効なディレクトリを指定します。ディレクトリの名前は、オペレーティング・システムに応じて適切に、スラッシュ (/) またはバックスラッシュ (\) で終わるようにします。また、これが既に存在するディレクトリで、ユーザがこれに対するアクセス権を持っていることを確認してください。

  2. ユーザの %Net.POP3Opens in a new tab インスタンスの Fetch() または FetchMessage() を呼び出します。

各ファイル名は、以下のとおり決定されます。

  1. Content-Disposition ヘッダでファイル名が指定されている場合、そのファイル名が使用されます。

  2. それ以外の場合、Content-Type ヘッダでファイル名が指定されていれば、そのファイル名が使用されます。

  3. それ以外の場合、システムは、ATTxxxxxx.dat の形式の名前を作成します。

以下の点に注意してください。

  • ファイルが既に存在する場合、添付はダウンロードされません。

  • AttachDir には、既定値はありません。

  • 添付のサイズは、InterSystems IRIS によっては制限されませんが、ファイル・システムによって制限される場合があります。

  • ここでは、Dir および FileName プロパティは使用されていません。これらのプロパティは、"メッセージへの添付の追加" で説明したとおり、添付をメール・メッセージにアップロードする場合にのみ関係します。

例 ： GetMsg()

以下のメソッド例は、%Net.POP3Opens in a new tab のインスタンスおよびメッセージ番号を指定すると、メッセージ全体を取得します。

ClassMethod GetMsg(server as %Net.POP3,msgno as %Integer) as %Net.MailMessage 
{
    Set status=server.Fetch(msgno,.msg)
    If $$$ISERR(status) {
       Do $System.Status.DisplayError(status) 
       Quit $$$NULLOREF
    }
    Quit msg
}

メッセージに添付があり、%Net.POP3Opens in a new tab サーバの StoreAttachToFile、StoreInlineToFile、および AttachDir の各プロパティを指定した場合、それらの添付は、このメソッドを呼び出したときに指定のディレクトリに保存されます。

添付されているメッセージの取得

メールボックスに接続している間は、受信トレイ内の電子メール・メッセージに添付されている電子メール・メッセージをダウンロードできます。そのためには、%Net.POP3Opens in a new tab インスタンスの GetAttachedEmail() メソッドを使用して、添付された電子メールのコンテンツを取得します。

%Net.MailMessagePartOpens in a new tab のインスタンスを指定した場合、このメソッドは、そのメッセージ部分のコンテンツを持つシングルパートのメッセージを返します。具体的には、添付された電子メール・メッセージから取られたデータで初期化された %Net.MailMessageOpens in a new tab のインスタンスを (出力パラメータとして) 返します。

調べて取得するメソッドの概要

このセクションでは、メッセージを調べ、取得する際に使用できる %Net.POP3Opens in a new tab のメソッドをすべてリストします。

Fetch()
method Fetch(MessageNumber As %Integer, 
             ByRef MailMsg As %Net.MailMessage,
             Delete As %Boolean = 0,
             messageStream As %BinaryStream) as %Status

MessageNumber によって指定されたメッセージを (参照によって) 返し、オプションでそのメッセージに削除するようマーク付けします。メッセージが既に削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。

messageStream が指定された場合、元のメッセージはこのバイナリ・ストリームに書き込まれます。

FetchFromStream()
method FetchFromStream(messageStream As %BinaryStream, ByRef Msg As %Net.MailMessage) as %Status

このメソッドは、Fetch() に messageStream 引数を指定した場合に使用します。

単一の電子メール・メッセージを指定されたバイナリ・ストリームから取得します。messageStream は、メッセージを含んだバイナリ・ストリームである必要があります。 このメッセージは Msg の参照によって返されます。これはマルチパート・メッセージとなる可能性があります。

FetchMessage()
method FetchMessage(MessageNumber As %Integer, 
                    ByRef From As %String, 
                    ByRef To As %String, 
                    ByRef Date As %String, 
                    ByRef Subject As %String, 
                    ByRef MessageSize As %Integer, 
                    ByRef MsgHeaders As %ArrayOfDataTypes, 
                    ByRef MailMsg As %Net.MailMessage, 
                    Delete As %Boolean = 0) as %Status

特定のメッセージ・ヘッダ、メッセージ・サイズ、メッセージ・ヘッダ配列、およびメッセージ自体を (参照によって) 返し、オプションでメッセージに削除するようマーク付けします。メッセージが既に削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。

FetchMessageHeaders()
method FetchMessageHeaders(MessageNumber As %Integer, 
                           ByRef MsgHeadersArray As %String) as %Status

メッセージ番号を指定すると、このメソッドは、そのメッセージのすべてのヘッダを含む配列を (参照によって) 返します。メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。

FetchMessageInfo()
method FetchMessageInfo(MessageNumber As %Integer, 
                        Lines As %Integer, 
                        ByRef From As %String, 
                        ByRef To As %String, 
                        ByRef Date As %String, 
                        ByRef Subject As %String, 
                        ByRef MessageSize As %Integer, 
                        ByRef MsgHeaders As %ArrayOfDataTypes, 
                        ByRef MessageText As %String) as %Status

メッセージ番号を指定すると、このメソッドは、特定のメッセージ・ヘッダ、メッセージ・サイズ、メッセージ・ヘッダの配列、およびこのメッセージのテキストの指定の行数を (参照によって) 返します。 メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。

GetAttachedEmail()
method GetAttachedEmail(msgpart As %Net.MailMessagePart, 
       Output mailmsg As %Net.MailMessage) as %Status

メッセージ部分を指定すると、このメソッドは、メッセージ部分からのデータで初期化されたシングルパートの電子メール・メッセージを (出力パラメータとして) 返します。

GetMessageUID()
method GetMessageUID(MessageNumber As %Integer, 
                     ByRef UniqueID As %String) as %Status

メッセージ番号を指定すると、メッセージの UID を (参照によって) 返します。メッセージ番号およびUID についての詳細は、前のセクションを参照してください。 メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。

GetMessageUIDArray()
method GetMessageUIDArray(MessageNumber As %String = "", 
                          ByRef ListOfUniqueIDs As %ArrayOfDataTypes) as %Status

最初の引数として空の文字列が指定されている場合、このメソッドは、メールボックス内のメッセージについての情報の配列を、参照によって返します (現在削除するようマーク付けされているものを除く)。この配列の各要素には、1 つのメッセージについての以下の情報が含まれています。

配列キー 配列項目
現在の状態でのメールボックス内のメッセージの番号。最初のメッセージが 1 番で、以降順次番号が割り当てられます。

指定したメッセージのメッセージ番号がすべてのセッションで同じであることは保証されません。

 すべてのセッションで使用できる、このメッセージの永久の識別子である、一意のメッセージ識別子 (UID)。

UID は、各メールボックスに対して一意です。

あるいは、メッセージ番号を指定すると、このメソッドは、そのメッセージの UID を含む 1 要素の配列を返します。この場合、メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。

GetSizeOfMessages()
method GetSizeOfMessages(MessageNumber As %String = "", 
                         ByRef ListOfSizes As %ArrayOfDataTypes) as %Status

最初の引数として空の文字列が指定されている場合、このメソッドは、メールボックス内のメッセージについての情報の配列を、参照によって返します (現在削除するようマーク付けされているものを除く)。この配列の各要素には、1 つのメッセージについての以下の情報が含まれています。

配列キー 配列項目
現在の状態でのメールボックス内のメッセージの番号。 このメッセージのサイズ (単位はバイト)。

あるいは、メッセージ番号を指定すると、このメソッドは、そのメッセージのサイズ (バイト単位) を含む 1 要素の配列を返します。この場合、メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。

メッセージの削除

メールボックスに接続している間は、そのメールボックス内で削除するようメッセージにマーク付けすることができます。これは、以下の 2 つの方法で行うことができます。

  • これには DeleteMessage() メソッドを使用できます。このメソッドは、削除するメッセージ番号である 1 つの引数を取ります。

  • Fetch() メソッドまたは FetchMessage() メソッドによってメッセージを取得する際、メッセージ取得後に削除するようメッセージにマーク付けするように POP3 サーバに指示するオプションの引数を指定できます。

以下の点に留意してください。

  • これらのメソッドは、メッセージを削除しません。削除するようこれにマーク付けします。メッセージは、QuitAndCommit() によって POP3 トランザクションを完了するまで削除されません。単にサーバから切断すると、変更は破棄されます。

  • RollbackDeletes() メソッドを呼び出してメッセージを変更し、削除のマーク付けを解除することができます。

  • これらの各メッセージはステータスを返すので、それを確認する必要があります。

例 ： GetMsgAndDelete() および CommitChanges()

以下の例は、メッセージを取得し、削除するようマーク付けします。

ClassMethod GetMsgAndDelete(ByRef server As %Net.POP3, msgno As %Integer) As %Net.MailMessage
{
  //third argument to Fetch says whether to 
  //mark for deletion
  Set status=server.Fetch(msgno,.msg,1)
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status) 
    Quit $$$NULLOREF
  }
  
  Quit msg
}

このメッセージは、%Net.POP3Opens in a new tab の変更バージョンを (参照によって) 返します。変更バージョンには、どのメッセージが削除するようマーク付けされているかについての情報が含まれています。

前述のメソッドを以下のようなメソッドと共に使用します。

ClassMethod CommitChanges(server As %Net.POP3) As %Status
{
  //commit all changes and log out
  Set status=server.QuitAndCommit()
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status) 
    Quit $$$ERROR($$$GeneralError,"Failed to commit changes")
  }
  Quit $$$OK
}

または、RollbackDeletes() や QuitAndRollback() によって変更をロールバックします。

関連項目

受信した電子メールの操作Next section
Previous sectionSMTP を介した電子メールの送信
FeedbackOpens in a new tab