Blocks

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

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

list

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 最大取得件数：100

レスポンス

JSONXML

{
"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 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

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	配信停止リストから削除する対象のメールアドレスを指定します。制約：削除対象のメールアドレスは大文字小文字無視の完全一致で検索します。

レスポンス

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

JSONXML

{
    "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	配信停止リストから削除する対象のメールアドレスを指定します。制約：削除対象のメールアドレスは大文字小文字無視の完全一致で検索します。

レスポンス

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

JSONXML

{
    "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