受信ファクスの一覧を取得

受信ファクスの一覧を取得

有効な MultiTEL API アカウントを使用し、設定済みの認証情報と IP 制限に従って HTTPS で接続してください。このエンドポイントは、認証されたアカウントに属する受信ファクスの一覧を返します。ファクスの送信や文書のダウンロードは行いません。

curl --silent --show-error --get --user "$API_USER:$API_PASSWORD" \
  --data-urlencode page=1 \
  --data-urlencode limit=25 \
  --data-urlencode date_from=2026-10-01 \
  --data-urlencode date_to=2026-10-02 \
  https://api.multitel.net/v3/fax_inbox

日付範囲は両端を含み、リクエストで指定されたユーザーのタイムゾーンではなく、API サーバーによる日付の解釈を使用します。不正な日付文字列は、拒否されずに無視される場合があるため、送信前に検証してください。日付フィルターを指定しない場合、ハンドラーは既定の日付範囲を適用しません。結果は受信時刻の新しい順に並びます。このエンドポイントは、複数ページにわたって状態を固定したスナップショットを提供しません。新しいファクスを受信すると、レコードが別のページに移る場合があります。

受信ボックスのページを読み取る

HTTP の結果と、JSON の status.code を確認してください。API の他の箇所で発生した失敗は、JSON 形式のエラー応答で返される場合があり、その際の HTTP ステータスが 200 であることもあります。成功した応答には response.faxes と response.pagination が含まれます。この例の値は架空のものです。

{
  "status": {"code": 200, "msg": ""},
  "response": {
    "faxes": [{
      "id": 12,
      "hash": "c20ad4d76fe97759aa27a0c99bff6710",
      "from_number": "+12125550123",
      "to_number": "+12125550124",
      "remote_station_id": "Example sender",
      "pages": 2,
      "cost": 0.05,
      "received_at": "2026-10-01 12:00:00",
      "received_timestamp": 1790856000,
      "status": "success",
      "status_text": "OK",
      "emailed": "yes",
      "viewed": false
    }],
    "pagination": {"page": 1, "limit": 25, "total": 1, "total_pages": 1}
  }
}

id は受信ボックスのレコードを識別する数値の ID です。 hash は、従来の受信文書処理で使用する、この ID の MD5 表現です。send_fax のジョブ ID でも認可用の認証情報でもありません。送信用の fax_status エンドポイントでは使用しないでください。

received_timestamp は保存されている Unix タイムスタンプです。 received_at は、タイムゾーンのオフセットを含まない、サーバーで書式設定されたタイムスタンプです。受信時刻が記録されていない場合は null になります。使用するタイムゾーンで時刻を表示する際は、Unix 値を使用してください。 cost は JSON の数値であり、見積価格でも、別途課金が完了したことを示す証拠でもありません。

status は、保存されたステータスコードがゼロの場合にのみ success となり、それ以外の値では failed となります。 status_text には保存された処理メッセージが入り、代替値として OK または Failed が使用されます。 emailed は真偽値ではなく、保存された値をそのまま保持します。 viewed は真偽値です。ファクスのステータスだけで、メールが正常に配信されたと判断しないでください。

空の一覧や変化する一覧への対応

受信ボックスが空の場合、空の faxes 配列と、値が 0 の total、値が 0 の total_pages が返されます。最終ページを超えるページを指定した場合も、空の配列が返されることがあります。少なくともページが存在すると仮定せず、ページ分割用フィールドに従って取得を終了してください。カーソルや、レコード ID による副次的な並べ替えは公開されていません。ページ間で重複するレコードを照合する際は、レコード ID を保持してください。

文書へのアクセスとプライバシー

受信ボックスの項目には、非公開の電話関連情報と文書のメタデータが含まれます。アプリケーション内でアクセスを制限し、応答全体をログに記録しないでください。一覧を取得しても文書は閲覧済みになりません。互換性維持のための受信文書のダウンロードには fax_file を使用してください。ただし、ファイルを利用できない場合でも、既存の受信レコードは閲覧済みになる点に注意してください。ポータルの受信ボックスからも文書にアクセスできます。ファイルの保持についての保証は確立されていません。