SMTP_transporter.send( )

4D v18

説明

SMTP_transporter.send( ) メソッドは、mail オブジェクト引数で指定されたメールメッセージを、transporter オブジェクトで定義されたSMTP サーバーへと送信し、ステータスオブジェクトを返します。

注: transporter オブジェクトは、事前にSMTP New transporter コマンドを使用して作成されている必要があります。

メソッドは、SMTP 接続が事前に開かれていなかった場合にはそれを作成します。transporter オブジェクトのkeepAlive プロパティがFalse であった場合、SMTP 接続はのSMTP_transporter.send( ) 実行後に自動的に閉じられます。そうでない場合、接続はtransporter オブジェクトが消去されるまで開いたままになります。詳細な情報については、SMTP New transporter コマンドの説明を参照して下さい。

mail 引数には、送信する有効なEメールオブジェクトを渡します。メールには送信元(メールがどこから送られるか)と送信先(一つまたはそれ以上の受信者)プロパティが含まれている必要がありますが、他のプロパティは任意です。サポートされるプロパティは以下の通りです:

プロパティ		型	詳細
from		テキスト \| オブジェクト \| コレクション(*)	送信元のアドレス(**)
cc		テキスト \| オブジェクト \| コレクション(*)	Carbon Copy (CC)の送信先。追加のEメール受信者。
bcc		テキスト \| オブジェクト \| コレクション(*)	Blind Carbon Copy (BCC)。非表示のEメール受信者。
to		テキスト \| オブジェクト \| コレクション(*)	メインの受信者。
sender		テキスト \| オブジェクト \| コレクション(*)	Eメールのソースのアドレス(**)
replyTo		テキスト \| オブジェクト \| コレクション(*)	返信先のアドレス
subject		テキスト	主題の詳細
textBody		テキスト	Eメールメッセージを標準テキストで表現したもの(デフォルトの文字セットはUTF-8 )(***)
htmlBody		テキスト	EメールメッセージをHTML で表現したもの(デフォルトの文字セットはUTF-8 )(***)
sendAt		テキスト	Eメールのタイムスタンプ(UTC日付)
attachments		オブジェクトのコレクション	attachment 引数オブジェクトのコレクション。詳細はMAIL New attachment参照
messageId		テキスト	メッセージ識別ヘッダー("message-id")。通常は、"lettersOrNumbers@domainname"であり、例えば "abcdef.123456@4d.com" などです。この固有IDは特にフォーラムや公開メーリングリストで使用されています。一般的に、メールサーバーはこのヘッダーを送信するメッセージに自動的に追加します。
inReplyTo		テキスト	カレントのメッセージが返信している、元のメッセージのメッセージID(****)
references		テキストのコレクション	繋がっている返信チェーン内のメッセージの、全てのメッセージIDのコレクション(****)
keywords		オブジェクト	"keywords" ヘッダー。キーワードのセットをオブジェクトとして格納し、そのプロパティ名がキーワードであり、それぞれの値はtrueになります。RFC#4021を参照してください。
	.<keyword>	ブール	設定するキーワード(値はtrue でなければなりません)。例: `$mail.keywords["$flagged"]:=True $mail.keywords["4d"]:=True`
comments		テキスト	追加のコメントのヘッダー。コメントはメッセージのヘッダーセクション内にのみ表示されます(つまり本文部分には触れないということです) (****)
headers		オブジェクトのコレクション	EmailHeader オブジェクトのコレクション。メッセージ内で現れる順番になっています。これによってユーザーは拡張された(登録された)ヘッダーやユーザー定義された(ただし登録されていない、"X"で始まる)ヘッダーを追加することができます。注: EmailHeader オブジェクトプロパティが、"from" または "cc" などのヘッダーを定義している時、これらがメールレベルですでにプロパティとして設定されている場合、EmailHeader プロパティは無視されます。
	[ ].name	テキスト	(必須) RFC#5322 で定義されているヘッダーフィールド名。null または未定義の場合には、ヘッダーフィールドはMIME ヘッダーには追加されません。
	[ ].value	テキスト	RFC#5322 で定義されているヘッダーフィールド名。

注: "Content-" で始まるヘッダーフィールドは、mail オブジェクトで指定してはいけません。

以下のプロパティは、mail オブジェクトがMIME ドキュメントからビルドされていた場合(例: MAIL Convert from MIME コマンドで生成された場合など)に使用される追加のプロパティです。この場合、bodyStructure および bodyValues プロパティは両方とも一緒に渡す必要があり、htmlBody および textBodyプロパティは使用しないことが推奨されます。

bodyStructure		オブジェクト	(オプション)メッセージ本文の完全なMIME ストラクチャー(EmailBodyPart オブジェクト)
	partID	テキスト	Eメール内でパーツを固有に識別するID
	type	テキスト	(必須)パーツのContent-Type ヘッダーフィールドの値
	charset	テキスト	Value of the charset parameter of the Content-Type header field
	encoding	テキスト	isEncodingProblem=true の場合Content-Transfer-Encoding の値が追加されます(デフォルトでは未定義)
	disposition	テキスト	パーツのContent-Disposition ヘッダーフィールドの値
	language	テキストのコレクション	パーツのContent-Language ヘッダーフィールド内にある、RFC3282 で定義されている言語タグの一覧(もしあれば)
	location	テキスト	Content-Location パーツのヘッダーフィールド内にある、RFC2557 で定義されているURI(もしあれば)
	subParts	オブジェクトのコレクション	それぞれの子の本文パート(EmailBodyPart オブジェクトのコレクション)
	headers	オブジェクトのコレクション	パーツ内にある全てのヘッダーフィールドの一覧(メッセージ内で出現する順)(EmailHeader オブジェクトのコレクション、header プロパティ参照)
bodyValues		オブジェクト	(オプション) EmailBodyValue オブジェクト。bodyStructure の各partIDのオブジェクトを格納
	<partID>.value	テキスト	本文パートの値
	<partID>.isEncodingProblem	ブール	文字セットをデコーディング中に、不正なフォーマットのセクション、未知の文字セット、あるいは未知のコンテンツtransfer-encodingが見つかった場合にはTrue。デフォルトはFalse

以下はbodyStructure and bodyValues オブジェクトの一例です:

"bodyStructure": {
  "type": "multipart/mixed",
  "subParts": [
    {
      "partId": "p0001",
      "type": "text/plain"
    },
    {
      "partId": "p0002",
      "type": "text/html"
    }
  ]
},
"bodyValues": {
  "p0001": {
    "value": "I have the most brilliant plan. Let me tell you all about it."
  },
  "p0002": {
    "value": "<!DOCTYPE html><html><head><title></title><style type=\"text/css\">div{font-size:16px}</style></head><body><div>I have the most brilliant plan. Let me tell you all about it.</div></body></html>"
  }
}

(*) Eメールアドレスを格納する全てのプロパティ(from, cc, bcc, to, sender, replyTo) はテキスト、オブジェクト型、コレクション型の値を受け付けます。

テキスト:
- 単一のEメールアドレスの場合: "somebody@domain.com"
- 単一の表示名+Eメールアドレスの場合: "Somebody <somebody@domain.com>"
- 複数のEメールの場合: "Somebody <somebody@domain.com>,me@home.org"
オブジェクト型:
二つのプロパティを持つオブジェクトです:
プロパティ 型詳細
name テキスト表示名(nullも可)
email テキスト Eメールアドレス
コレクション型:
アドレスオブジェクトのコレクション

(**) 送信されるEメールはsender および from の両方のアドレスを持っています:

sender ドメインは、セッションを開いたときに受信側のEメールサーバーが受け取るドメインです。
from アドレスは、受信者に表示されるアドレスです。
分かりやすい配信のためには、同じfrom および sender アドレスを使用することが推奨されます。

(***) textBody と htmlBody の両方が渡されていた場合、のMIME コンンテンツ型が使用されます。その場合Eメールクライアントはマルチパート/代替パートを自動的に認識し、必要に応じてテキストパートあるいはHTMLパートを表示するようになっています。

(****) 特殊なフォーマット要件に関しては、RFC#5322 を参照してください。

注: 4D はJMAP specification に従ってmail オブジェクトの成型をします。

返されるオブジェクト

SMTP_transporter.send( ) はオペレーションのSMTP ステータスを記述するオブジェクト型を返します。オブジェクトには以下のプロパティが格納されています:

プロパティ	型	詳細
success	ブール	送信オペレーションに成功した場合にはTrue、そうでない場合にはFalse
status	数値	SMTP サーバーから返されたコード
statusText	テキスト	SMTP サーバーから返されたメッセージ

注: SMTP ステータスコードにの情報については、こちらのページを参照して下さい。

エラーハンドリング

SMTP 処理とは関係ない問題(例: mail オブジェクトの必須プロパティが不足しているなど)の場合、4D はON ERR CALL コマンドで実装されたメソッドで割り込み可能なエラーを生成します。エラーについての情報については、GET LAST ERROR STACK コマンドを使用してください。

この場合、返されるステータスオブジェクトには以下の値が格納されます:

success: false
status: 0
statusText: "Email Sending Failure"

例題

以下のコードは、Eメールをビルドし、送信します:

 C_OBJECT($server)

 $server:=New object

 $server.host:="mail.smtp.host" // 必須

 $server.port:=25 // 任意、デフォルト値: 587

 

 $transporter:=SMTP New transporter($server)

 

 C_COLLECTION($headers) //ユーザーが定義したヘッダーを追加

 $headers:=New collection

 $headers.push(New object("name";"X-MAILER";"value";"MySoftware"))

 $headers.push(New object("name";"X-4D-VERSION";"value";"17Rx"))

 

 C_OBJECT($email)

 $email:=New object

 $email.subject:="my first mail"

 $email.to:="test.mail@4d.com"

 $email.from:="test.noreply@4d.com"

 $email.textBody:="this is a test"

 $email.attachments:=New collection(MAIL New attachment("schedule.xlsx"))

 $email.headers:=$headers

 $email.keywords:=New object("technical";True;"advanced";True;"useless";False)

 

 $status:=$transporter.send($email)

 If(Not($status.success))

    ALERT("An error occurred sending the mail: "+$status.statusText)

 End if

参照

MAIL Convert from MIME
MAIL Convert to MIME
MAIL New attachment
SMTP New transporter
SMTP_transporter.checkConnection( )