Blocks

Blocks はアカウントが存在しないなどの理由により送信エラーが発生したため、配信停止状態に あるメールアドレスを検索・参照する、ダウンロードする、配信停止状態を解除する等の操作を提供します。

このAPIは管理コンソールが提供します。接続先ホストについては共通仕様を参照ください。


list

Pro

Blocks/list は、配信停止状態にあるメールアドレスを検索・参照する操作を提供します。

リクエスト

/transaction/v2/blocks/list.[json|xml]

アクセス制御

項目
ロール APIグループ管理者、APIユーザ
権限 データ参照許可

パラメータ

パラメータ 必須 データ型 説明
api_user Yes ASCII ユーザ認証に使用するIDを指定します。
api_key Yes ASCII ユーザ認証に使用するシークレットキーを指定します。
server_composition Yes UTF-8 操作の対象となるサーバ構成の名称を指定します。
email No ASCII このパラメータが指定された場合、部分一致するメールアドレスを検索します。
start_date No DATE 配信停止状態となった日を基準とした期間検索を行うために検索開始日(yyyy-mm-dd)を指定します。検索開始日は検索期間に含まれます。
制約:start_dateはend_dateと等しいか過去日を指定しなければなりません。
end_date No DATE 配信停止状態となった日を基準とした期間検索を行うために検索終了日(yyyy-mm-dd)を指定します。検索終了日は検索期間に含まれます。
removed No BOOLEAN 配信停止状態を解除したメールアドレスを取得する場合、trueを指定します。
デフォルト:false
p No INTEGER 参照するページ位置を指定します。
デフォルト:0
r No INTEGER 1ページに表示するレコード数を指定します。
デフォルト:10

レスポンス

JSON

{
  "blocks": [
    {
      "created": "2015-12-14 08:46:00",
      "email": "to1@example.com",
      "id": "cp0ihzuyl3445",
      "occurred": "1",
      "status": "2"
    },
    {
      "created": "2015-12-14 12:19:00",
      "email": "to2@example.com",
      "id": "cp0ihzuyl3479",
      "occurred": "1",
      "status": "2"
    }
    ...
  ]
}

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<blocks>
  <block>
    <id>cp0ihzuyl3445</id>
    <email>to1@example.com</email>
    <status>2</status>
    <occurred>1</occurred>
    <created>2015-12-14 08:46:00</created>
  </block>
  <block>
    <id>cp0ihzuyl3479</id>
    <email>to2@example.com</email>
    <status>2</status>
    <occurred>1</occurred>
    <created>2015-12-14 12:19:00</created>
  </block>
</blocks>
プロパティ 説明
id データ識別子
email 配信停止状態にあるメールアドレス(removed=trueの場合、配信停止を解除したメールアドレス)。
status エラーステータス(エラーステータスの値については、こちらを参照)
occurred 送信エラーが発生した回数
created 配信停止状態とした日時

エラーメッセージ

フィールド エラーコード メッセージ(en) メッセージ(ja)
server_composition 10-002 Specified server composition, {0}, was not found. 指定されたサーバ構成 {0} は存在しません。
start_date 10-003 The start_date must be earlier than the end_date. 開始日には終了日以前の日付を指定してください。
12-002 Access to the specified data was denied. 指定されたデータにアクセスする権限がありません。

リクエスト例

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=testcomp' https://api.smtps.jp/transaction/v2/blocks/list.json

download

Pro

Blocks/download は、配信停止状態にあるメールアドレスを検索し、 CSVファイル形式でダウンロードする操作を提供します。

リクエスト

/transaction/v2/blocks/download.[json|xml]

アクセス制御

項目
ロール APIグループ管理者、APIユーザ
権限 ダウンロード許可

パラメータ

パラメータ 必須 データ型 説明
api_user Yes ASCII ユーザ認証に使用するIDを指定します。
api_key Yes ASCII ユーザ認証に使用するシークレットキーを指定します。
server_composition Yes UTF-8 操作の対象となるサーバ構成の名称を指定します。
email No ASCII このパラメータが指定された場合、部分一致するメールアドレスを検索します。
start_date No DATE 配信停止状態となった日を基準とした期間検索を行うために検索開始日(yyyy-mm-dd)を指定します。検索開始日は検索期間に含まれます。
制約:start_dateはend_dateと等しいか過去日を指定しなければなりません。
end_date No DATE 配信停止状態となった日を基準とした期間検索を行うために検索終了日(yyyy-mm-dd)を指定します。検索終了日は検索期間に含まれます。
removed No BOOLEAN 配信停止状態を解除したメールアドレスを取得する場合、trueを指定します。
デフォルト:false

レスポンス

リクエストが成功した場合、Content-Type に application/octet-stream を指定し、 以下フォーマットのCSVファイルをZIP圧縮してダウンロードします。データ暗号化を設定している場合、 パスワード付き暗号化ZIPファイルをダウンロードします。

ファイル名

blocks-yyyyMMdd_HHmmss.zip (例; blocks-20151207_175202.zip)

ファイルフォーマット

"created","id","email","status","occurred"
"2015-12-14 08:46:00","cp0ihzuyl3445","from1@example.com","2","1"
"2015-12-14 12:19:00","cp0ihzuyl3479","from2@example.com","2","1"
プロパティ 説明
created 配信停止状態とした日時
id データ識別子
email 配信停止状態にあるメールアドレス(removed=trueの場合、配信停止を解除したメールアドレス)。
status エラーステータス
occurred 送信エラーが発生した回数

エラーメッセージ

フィールド エラーコード メッセージ(en) メッセージ(ja)
server_composition 10-002 Specified server composition, {0}, was not found. 指定されたサーバ構成 {0} は存在しません。
start_date 10-003 The start_date must be earlier than the end_date. 開始日には終了日以前の日付を指定してください。
12-002 Access to the specified data was denied. 指定されたデータにアクセスする権限がありません。

リクエスト例

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=testcomp' https://api.smtps.jp/transaction/v2/blocks/download.json > data.zip

delete

Blocks/delete は、配信停止状態にあるメールアドレスを恒久的に送信可能にする操作を提供します。 本操作を行ったメールアドレスのメール送信を許可し、配信エラーが再発した場合でも、配信停止の対象にならないよう制御します。

配信エラーの誤判定があった場合や、運用上必ずメール送信を試行する必要があるメールアドレスなど、 メールアドレスを恒久的に送信可能な状態としたい場合、本APIにて該当するメールアドレスを操作してください。

リクエスト

/transaction/v2/blocks/delete.[json|xml]

アクセス制御

項目
ロール APIグループ管理者
権限 なし

パラメータ

パラメータ 必須 データ型 説明
api_user Yes ASCII ユーザ認証に使用するIDを指定します。
api_key Yes ASCII ユーザ認証に使用するシークレットキーを指定します。
server_composition Yes UTF-8 操作の対象となるサーバ構成の名称を指定します。
email Yes ASCII 配信停止リストから削除する対象のメールアドレスを指定します。
制約:削除対象のメールアドレスは大文字小文字無視の完全一致で検索します。

レスポンス

処理が成功した場合、以下の応答メッセージになります。

{
    "message" : "success"
}
<success>
    <message>success</message>
</success>

エラーメッセージ

フィールド エラーコード メッセージ(en) メッセージ(ja)
server_composition 10-002 Specified server composition, {0}, was not found. 指定されたサーバ構成 {0} は存在しません。
email 12-001 It does not exist the data specified in the email. emailで指定されたデータは存在しません。

リクエスト例

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=testcomp' -d 'email=test@example.com' https://api.smtps.jp/transaction/v2/blocks/delete.json

cancel

Blocks/cancel は、配信停止状態にあるメールアドレスを取り消しする操作を提供します。 本操作を行ったメールアドレスのメール送信を許可しますが、配信エラーが再発し、配信停止条件合致した場合は、配信停止とするよう制御します。

メール受信者側の迷惑メールフィルタの設定など復旧可能な理由により、配信停止となったメールアドレスを取り消したい場合、 本APIにて該当するメールアドレスを操作してください。

リクエスト

/transaction/v2/blocks/cancel.[json|xml]

アクセス制御

項目
ロール APIグループ管理者
権限 なし

パラメータ

パラメータ 必須 データ型 説明
api_user Yes ASCII ユーザ認証に使用するIDを指定します。
api_key Yes ASCII ユーザ認証に使用するシークレットキーを指定します。
server_composition Yes UTF-8 操作の対象となるサーバ構成の名称を指定します。
email Yes ASCII 配信停止リストから削除する対象のメールアドレスを指定します。
制約:削除対象のメールアドレスは大文字小文字無視の完全一致で検索します。

レスポンス

処理が成功した場合、以下の応答メッセージになります。

{
    "message" : "success"
}
<success>
    <message>success</message>
</success>

エラーメッセージ

フィールド エラーコード メッセージ(en) メッセージ(ja)
server_composition 10-002 Specified server composition, {0}, was not found. 指定されたサーバ構成 {0} は存在しません。
email 12-001 It does not exist the data specified in the email. emailで指定されたデータは存在しません。

リクエスト例

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=testcomp' -d 'email=test@example.com' https://api.smtps.jp/transaction/v2/blocks/cancel.json