SMTPアクション

smtpアクションはSMTPサーバーへメールを配送します。任意の本文を書いて通知を送るためのものではなく、配送そのものを計測・負荷試験するためのアクションです。本文は自動生成され、サイズはlengthで指定します。

基本的な構文

SMTPのステップでは、サーバー、エンベロープのアドレス、送信内容を指定します。

steps:
  - name: Send a probe mail
    uses: smtp
    with:
      addr: "localhost:2525"
      from: "sender@example.com"
      to: "recipient@example.com"
      subject: "Delivery probe"
      session: 1
      message: 1
      length: 500
    test: res.code == 0 && res.sent > 0

パラメータ

以下のフィールドで配送内容を指定します。いずれもテンプレート式を書けます。

STARTTLSの後はサーバーの証明書をaddrのホストで検証するため、自己署名の証明書やホストの合わない証明書は、insecure_skip_tlsを指定しない限りセッションを失敗させます。ポート465のように最初からTLSで始まる接続には対応していません。認証、CC/BCC、任意の本文やHTMLを指定するパラメータはありません。実行結果にレポートを出したい場合はステップのechoを使います。

timeoutには10sや1m30sのような時間の文字列か、秒数を書きます。時間でも数でもない値、0以下の値、24hを超える値はエラーになります。上限はセッション全体ではなく1回ごとの待ちに掛かるため、サーバーが応答し続ける限り、多くのメッセージを送るセッションはtimeoutより長くかかっても構いません。サーバーは応答の前にメッセージを検査することがあるため、メッセージの終わりへの応答はtimeoutの2倍（デフォルトでは2分）まで待ちます。この応答が時間切れになったメッセージは、サーバーが受け取っていても失敗として数えます。時間内に応答しないサーバーのセッションは失敗し、1通も配送できなかった場合はmail delivery failed: tcp dial error: read tcp ...: i/o timeout (the server did not answer within 1m0s)のようなエラーでステップが終わります。

セッション全体の上限は、ステップ自体のtimeout（デフォルトは5m）です。待ちがどう進んでもアクションはそこで止まり、テストできるresは残りません。timeoutのデフォルトはこれより十分に短いため、応答しなくなったサーバーのセッションはその前に失敗し、ステップは全セッションの通数を返せます。RFC 5321（4.5.3.2節）は、クライアントがほとんどの応答を5分、メッセージの終わりへの応答を10分待つよう求めています。グレイリスティングをするサーバーや、メッセージごとに検査をするサーバーのような遅いサーバーに送る場合は、両方を延ばします。1回ごとの待ちはwith.timeoutで、ステップのtimeoutはセッション全体にかかりうる時間より長くします。

- name: Deliver to a slow server
  uses: smtp
  timeout: 30m
  with:
    addr: "mx.example.com:25"
    from: "sender@example.com"
    to: "recipient@example.com"
    timeout: 5m

生成するメッセージにはFrom、To、Date、Subjectのヘッダーが付きます。本文はThis is a test mail.の後にlength個の*を続けたもので、80文字ごとに改行します。送るときには、メッセージごとにこれらの前へ2つのヘッダーを足します。送信した時刻をUnixナノ秒で表すX-Send-Timestamp-Nsと、メッセージごとのMessage-IDです。Message-IDの@より前の部分は、件名の末尾にも - <id>の形で付けます。メッセージは送り始めるときに一度だけ作るため、1つのステップのメッセージはすべて同じDateを持ちます。各メッセージを送った時刻はX-Send-Timestamp-Nsに入ります。

レスポンスオブジェクト

実行後、resに配送の結果が入ります。

サーバーがメールを拒否した場合（RCPT TOへの550など）はサーバーが応答しているので、ステップはそのままテストに進みます。このときres.codeは1になり、応答はres.errorに入ります。どのセッションもサーバーに接続できなかった場合は、エラーとしてステップが終わります。

使用例

以下の例では、生成したメッセージを送信し、その件数を後続のステップから参照します。

複数セッション・複数通の配送

messageは合計の通数で、セッションに振り分けられます。この例では、一方のセッションが2通、もう一方が1通を配送します。

steps:
  - name: Deliver 3 messages over 2 sessions
    id: bulk
    uses: smtp
    with:
      addr: "{{vars.smtp_addr}}"
      from: "{{vars.from_addr}}"
      to: "{{vars.to_addr}}"
      subject: "Bulk delivery test"
      myhostname: probe-client.local
      session: 2
      message: 3
      length: 750
    test: res.code == 0 && res.sent == 3
    outputs:
      sent: res.sent
      elapsed: rt.duration

結果をレポートする

出力として取り出した件数は、後続のステップから出力できます。

  - name: Delivery summary
    uses: hello
    echo: |
      Sent: {{outputs.bulk.sent}}
      Took: {{outputs.bulk.elapsed}}

関連項目

• Mail Latency - 配送遅延の計測
• IMAP - メールボックスの操作
• YAML設定 - ステップのプロパティ