blastengine API (1.10.0)

blastengine API の利用に関して

API の利用には、blastengineのサービス利用規約が適用され、API を利用すると同利用規約に同意したものとみなされます。

認証について

APIキー発行時に作成される BearerToken を Authorization ヘッダにセットしてリクエストをサーバーに発行することでAPIを利用できます。 BearerToken はユーザごとに異なりますので、 BearerToken を使うことでそのユーザのアクセス権を保持しているということになります。

概要

API を利用する際の共通仕様は以下のとおりです。

項目	説明
APIのバージョン	1.10.0
使用するプロトコル	HTTPS
文字コード	UTF‒8

リクエストヘッダ

API をリクエストする場合には、以下の共通リクエストヘッダが必要です。

ヘッダ	説明
Authorization	ユーザー認証情報
Content-Type	添付データのコンテンツの種類 ( `application/json` / `multipart/form-data`(一部))
Accept-Language	ロケール情報 ( `ja-JP` / `en-US` )

レスポンスヘッダ

サーバから共通して返されるレスポンスヘッダは以下です。

ヘッダ	説明
X-RateLimit-Remaining	アクセス可能な残りの回数
X-Rate-Limit-Retry-After-Seconds	アクセス回数がリセットされるまでの時間(秒)

API BearerToken

API利用時には、前項で作成した BearerToken を利用して以下のようなリクエストをサーバーに発行します。
[BearerToken]には作成した BearerToken を入れてください。

curl https://app.engn.jp/api/v1/XXXXX -H "Authorization: Bearer [BearerToken]"

※ API BearerToken の生成方法
下記に記載する手順で生成してください。
[前提] API BearerToken の生成には apiKey が必要です。
apiKeyの発行・再発行は管理画面上から行ってください。

ログインID + apikey に Sha256 をかけます。コマンド実行時に表示されるハイフンは省いてください。
大文字は全て小文字化します。
base64 エンコードをかけます。エンコード結果に改行が含まれる場合、改行を削除をしてください。

echo -n 'ログインID + apikey' | shasum -a 256
出力された文字列を全て小文字化します
echo -n '小文字化した文字列' | base64

利用例

以下の例をご利用の場合、記載の順にAPIを実施してください。

・利用例A：トランザクション配信

配信登録(トランザクション) API
配信状況は配信詳細 APIの配信ステータスをご確認ください。

・利用例B：一斉配信

配信登録: 開始(一斉配信) API
発行した配信IDに対して、以下のいずれかを利用して配信先アドレスを登録します。 - 配信登録: 更新(一斉配信) API
- 配信先アドレス登録API
- 配信先アドレス一括登録ジョブの開始 API
配信登録: 完了(一斉配信) API で配信予約日時の登録をします。
配信予約日時経過後の配信状況は配信詳細 APIの配信ステータスをご確認ください。

**※配信数によっては全てのメール配信処理完了までに時間がかかる可能性があります。**

・利用例C：配信先アドレス一括登録

配信先アドレス一括登録ジョブの開始 API
ジョブの実行結果は配信先アドレス一括登録ジョブの取得 APIから確認できます。 - 一部成功や全て失敗している場合、エラーの内容が出力されたCSVのダウンロードURLが発行されている場合があります。
2.でダウンロードURLが発行された場合、配信先アドレス一括登録エラーCSVダウンロード APIからエラー内容を確認いただき、
再度1.を実施してください。

Rate Limit

Rate Limitは500req/mでございます。 blastengine APIには、サーバー負荷を抑える目的で呼び出し回数制限の仕組みが実装されています。
1分間に500回を超えた場合はリクエスト数制限超過エラーになります。
※呼び出し回数制限値は予告なく変更する場合がございます。

配信登録上限

blastengine APIで登録できる配信の数には上限がございます。
配信ステータスがEDITの配信が30件になりますと、それ以上配信登録ができなくなります。
追加で配信登録を行う場合、EDITの配信を完了させるか、削除する必要がございます。

HTTPステータスコード

コード	種別	説明
200	OK	リクエスト成功
201	Created	リクエストは成功し、新たなリソースが作成された
400	Bad Request	リクエスト値が不正
401	Unauthorized	認証エラー
403	Forbidden	API 利用権限なし
404	Not Found	指定リソースが存在しない
405	Method Not Allowed	指定HTTPリクエストメソッドがサポートされていない
415	Unsupported Media Type	指定したリクエストの形式がサポートされていない
423	Locked	アクセス中アカウントのロック
429	Too Many Requests	リクエスト数制限超過
500	Internal Server Error	サーバエラー
502	Bad Gateway	web通信の高負荷によるエラー

各種ステータス・種別一覧

送信メール文字コード

送信メール文字コード

UTF-8

ISO-2022-JP
配信種別

配信種別説明

TRANSACTION 即時配信

BULK 一斉配信

SMTP SMTP配信

送信メール文字コード
UTF-8
ISO-2022-JP

配信種別	説明
TRANSACTION	即時配信
BULK	一斉配信
SMTP	SMTP配信

配信ステータス

ステータス	説明
EDIT	編集中
IMPORTING	配信アドレス一括インポート中
RESERVE	配信予約済
WAIT	配信待ち
SENDING	配信中
SENT	配信成功
FAILED	配信失敗

最終送信ステータス

ステータス説明

SENT 配信成功

RETRY 再送

HARDERROR ハードエラー

SOFTERROR ソフトエラー

DROP エラー停止アドレスに合致
ジョブステータス

ステータス説明

WAIT 処理待ち

STARTED 処理中

FINISHED 完了

FAILED 処理失敗

STOP 停止

SYSTEM_ERROR システムエラー

TIMEOUT タイムアウト

ステータス	説明
SENT	配信成功
RETRY	再送
HARDERROR	ハードエラー
SOFTERROR	ソフトエラー
DROP	エラー停止アドレスに合致

ステータス	説明
WAIT	処理待ち
STARTED	処理中
FINISHED	完了
FAILED	処理失敗
STOP	停止
SYSTEM_ERROR	システムエラー
TIMEOUT	タイムアウト

処理種別

処理種別	説明
DELIVERIES_TRANSACTION	トランザクションメール
DELIVERIES_BULK	一斉配信メール
MESSAGES_IMPORT	メッセージ登録一括インポート
MAIL_OPEN	メール開封CSV生成
ERRORS_DOWNLOAD	エラーリストCSV生成

レスポンスコード

コード番号	内容
250	配信に成功しました
421	宛先サーバから一時的に拒否されました
450	一時的に宛先のメールボックスが利用できません
451	宛先サーバで一時的なエラーが発生しました
452	宛先サーバのシステムリソースが不足しています
453	宛先サーバで一時的なエラーが発生しました
454	内部処理中にエラーが発生しました
500	1行に対する文章が長すぎるため受け付けられません
521	宛先のメールボックスがいっぱいです
530	宛先サーバへの送信には認証または暗号化が必要です
550	宛先のメールアドレスがありません
550(rejection)	宛先サーバから受信拒否を受けました
551	宛先のメールアドレスがありません
552	宛先のメールボックスがいっぱいです
553	宛先のメールボックスが利用できません
554	宛先サーバでエラーが発生しました
554(banned)	配信が禁止されたアドレスへの配信のためブロックしました
554(errors)	エラー停止リストに含まれる宛先であるため、配信がドロップされました

添付ファイルのサイズ制限と種類

blastengine では添付できるファイルのサイズには制限があり、契約により異なります(デフォルトは1MB)。
制限内であれば複数のファイルを添付できます。

またセキュリティ上の理由により次の種類のファイルは添付できません。

添付不可能な拡張子
.ade, .adp, .apk, .appx, .appxbundle, .bat, .bz2, .cab, .chm, .cmd, .com, .cpl, .dll, .dmg, .ex, .ex_, .exe, .gz, .hta, .ins, .isp, .iso, .jar, .js, .jse, .lib, .lnk, .mde, .msc, .msi, .msix, .msixbundle, .msp, .mst, .nsh, .pif, .ps1, .scr, .sct, .shb, .sys, .tgz, .vb, .vbe, .vbs, .vxd, .wsc, .wsf, .wsh, .zip

差し込みコードについて

blastengine では、差し込み機能を提供しております。送信先アドレス毎にメール本文の一部（お名前や会社名など）だけが異なるメールを送ることができますので、宛先毎に合わせてパーソナライズされたメールの送信が可能になります。

差し込みコードのご利用方法

差し込みコードのkeyを予め、メールの本文(text_part、html_part)に設定しておくことで、
メール送信時、差し込みコードのvalueに置き換えられます。また、差し込みコードの設定上限は50件でございます。

差し込みコード

key __prop1__ __prop2__ __prop3__

value テスト太郎 123456 ブラストエンジン
本文差し込みイメージ

key	__prop1__	__prop2__	__prop3__
value	テスト太郎	123456	ブラストエンジン

__prop1__ 様    

 （会員番号 __prop2__）    

  __prop3__ をご利用いただきありがとうございます。

テスト太郎 様    

 （会員番号 123456）    

  ブラストエンジン をご利用いただきありがとうございます。

配信の保管期限について

配信が開始されてから`62`日経過後に、配信情報とそれに関わる配信先アドレス、配信ログ情報は`全て削除`されます。

エラー停止について

1つの宛先に対し2週間以内に2度以上のハードエラーが発生すると、宛先はエラー停止対象となります。期間は最大で2週間となります。

deliveries

配信一覧

※配信の保管期限があります。ご注意ください。

query Parameters

text_part	string <= 300 characters テキストパート(正規表現不可, 部分一致)
html_part	string <= 300 characters HTMLパート(正規表現不可, 部分一致)
subject	string <= 30 characters 件名(正規表現不可, 部分一致)
from	string <= 254 characters 送信元アドレス(正規表現不可, 部分一致)
status[]	Array of strings <= 10 items Example: status[]=EDIT&status[]=SENT 配信ステータス
delivery_type[]	Array of strings <= 10 items Example: delivery_type[]=TRANSACTION&delivery_type[]=BULK 配信種別(TRANSACTION \| BULK \| ALL)
delivery_start	string yyyy-MM-ddTHH:mm:ss+09:00 配信日時(開始位置) ISO 8601拡張形式のdate-time値
delivery_end	string yyyy-MM-ddTHH:mm:ss+09:00 配信日時(終了位置) ISO 8601拡張形式のdate-time値
size	integer [ 1 .. 1000 ] Default: 100 1ページ辺りの要素数
page	integer [ 1 .. 1000 ] Default: 1 取得するページ数 (1 indexed)
sort	string Default: "delivery_time:desc" 並び替え条件カンマ区切りにより複数指定可 (指定可能なソート = delivery_time:[asc\|desc], updated_time:[asc\|desc])

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"data": [{"delivery_id": 1,
"from": {"email": "sample_1@example.com",
"name": "送信者サンプル1"
},
"status": "SENT",
"delivery_time": "2021-11-11T00:00:00+09:00",
"updated_time": "2021-11-01T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"reservation_time": "2021-11-11T00:00:00+09:00",
"delivery_type": "BULK",
"subject": "件名サンプル Vol.1"
},
{"delivery_id": 2,
"from": {"email": "sample_2@example.com",
"name": "送信者サンプル2"
},
"status": "FAILED",
"delivery_time": "2021-01-11T12:34:56+09:00",
"updated_time": "2021-01-02T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"reservation_time": "2021-01-11T12:34:00+09:00",
"delivery_type": "TRANSACTION",
"subject": "件名サンプル Vol.2"
},
{"delivery_id": 3,
"from": {"email": "sample_3@example.com",
"name": "送信者サンプル3"
},
"status": "WAIT",
"delivery_time": "2021-01-11T12:34:56+09:00",
"updated_time": "2021-01-02T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"reservation_time": "2021-01-11T12:34:00+09:00",
"delivery_type": "BULK",
"subject": "件名サンプル Vol.3"
},
{"delivery_id": 4,
"from": {"email": "sample_4@example.com",
"name": "送信者サンプル4"
},
"status": "WAIT",
"delivery_time": "2021-01-11T12:34:56+09:00",
"updated_time": "2021-01-02T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"reservation_time": "2021-01-11T12:34:00+09:00",
"delivery_type": "BULK",
"subject": "件名サンプル Vol.4"
}
]
}

配信登録(トランザクション)

配信種別を TRANSACTION として配信IDを新規発行し、配信を実施します。

※発行されたIDは照会、変更および削除の操作を行う際に必要になります。

※配信の保管期限があります。ご注意ください。

header Parameters

Authorization

required

string

認証トークン

Request Body schema:
application/json

required	object 送信元情報
to required	string [ 6 .. 254 ] characters 宛先
cc	Array of strings <= 10 items CC
bcc	Array of strings <= 10 items BCC
	Array of objects <= 50 items 差し込みコード
subject required	string [ 1 .. 150 ] characters 件名
encode	string Default: `UTF-8` 送信メール文字コード
text_part required	string <= 30 kb テキストパート
html_part	string <= 70 kb HTMLパート

Responses

Request samples

Payload

Content type

application/json

{"from": {"email": "sample@example.com",
"name": "送信者サンプル"
},
"to": "sample_1@example.jp",
"cc": ["sample_2@example.jp"
],
"bcc": ["sample_3@example.jp"
],
"insert_code": [{"key": "__code1__",
"value": "差し込みコードサンプル1"
},
{"key": "__code2__",
"value": "差し込みコードサンプル2"
}
],
"subject": "テスト件名",
"encode": "ISO-2022-JP",
"text_part": "テスト配信",
"html_part": "<!DOCTYPE html><html><header></header><body>sample html</body></html>"
}

Response samples

201
400
401
500

Content type

application/json

{"delivery_id": 1
}

配信登録: 開始(一斉配信)

配信種別を BULK 、配信ステータスを EDIT として配信IDを新規発行します。

※発行されたIDは照会、変更および削除の操作を行う際に必要になります。

※配信の保管期限があります。ご注意ください。

header Parameters

Authorization

required

string

認証トークン

Request Body schema:
application/json

required	object 送信元情報
encode	string Default: `UTF-8` 送信メール文字コード
subject required	string [ 1 .. 150 ] characters 件名
text_part required	string <= 30 kb テキストパート
html_part	string <= 70 kb HTMLパート

Responses

Request samples

Payload

Content type

application/json

{"from": {"email": "sample@example.com",
"name": "送信者サンプル"
},
"encode": "ISO-2022-JP",
"subject": "テスト件名",
"text_part": "テスト配信",
"html_part": "<!DOCTYPE html><html><header></header><body>sample html</body></html>"
}

Response samples

201
400
401
500

Content type

application/json

{"delivery_id": 1
}

配信登録: 更新(一斉配信)

指定した配信IDの配信ステータスが EDIT の場合に情報を更新します。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Request Body schema: application/json

	object 送信元情報
	Array of objects 宛先 (上限50件。すでに宛先が登録済みの場合、消去後に登録されます。)
subject	string [ 1 .. 150 ] characters 件名
text_part	string <= 30 kb テキストパート
html_part	string <= 70 kb HTMLパート

Responses

Request samples

Payload

Content type

application/json

{"from": {"email": "sample@example.com",
"name": "送信者サンプル"
},
"to": [{"email": "sample_1@example.jp",
"insert_code": [{"key": "__code1__",
"value": "差し込みコードサンプル1"
},
{"key": "__code2__",
"value": "差し込みコードサンプル2"
}
]
},
{"email": "sample_2@example.jp",
"insert_code": [{"key": "__code1__",
"value": "差し込みコードサンプル1"
}
]
}
],
"subject": "テスト件名",
"text_part": "テスト配信",
"html_part": "<!DOCTYPE html><html><header></header><body>sample html</body></html>"
}

Response samples

200
400
401
500

Content type

application/json

{"delivery_id": 1
}

配信登録: 完了(一斉配信: 予約)

指定した配信を 配信予約日時 に一斉配信します。
指定した配信IDの配信ステータスを RESERVE に更新します。
配信先アドレスが1件以上設定されている必要があります。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Request Body schema: application/json

reservation_time

required

string yyyy-MM-ddTHH:mm:ss+09:00

配信予約日時
ISO 8601拡張形式のdate-time値

Responses

Request samples

Payload

Content type

application/json

{"reservation_time": "2021-01-11T12:34:00+09:00"
}

Response samples

200
400
401
500

Content type

application/json

{"delivery_id": 1
}

配信登録: 完了(一斉配信: 即時)

指定した配信を 即時 一斉配信します。
配信先アドレスが1件以上設定されている必要があります。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"delivery_id": 1
}

配信詳細

※配信の保管期限があります。ご注意ください。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"delivery_id": 1,
"from": {"email": "sample@example.com",
"name": "送信者サンプル"
},
"status": "RESERVE",
"delivery_time": "2021-01-11T12:34:56+09:00",
"updated_time": "2021-01-02T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"reservation_time": "2021-01-11T12:34:00+09:00",
"text_part": "テキストサンプル",
"html_part": "<!DOCTYPE html><html><header></header><body>sample html</body></html>",
"delivery_type": "BULK",
"subject": "件名サンプル Vol.5",
"attaches": [{"delivery_attach_id": 1,
"file_name": "sample.txt",
"mime": "application/text",
"size": 100,
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
},
{"delivery_attach_id": 2,
"file_name": "sample.pdf",
"mime": "application/pdf",
"size": 100,
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
}
],
"open_count": 220,
"total_count": 2100,
"sent_count": 1950,
"drop_count": 50,
"soft_error_count": 50,
"hard_error_count": 50
}

配信削除

指定した配信IDの配信ステータスが SENDING, WAIT, IMPORTING に該当しない場合に、配信IDを削除します。
※配信の保管期限があります。ご注意ください。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"delivery_id": 1
}

配信キャンセル

指定した配信IDの配信ステータスを EDIT に更新します。
配信IDの配信ステータスが EDIT, RESERVE, WAIT のいずれかで、配信種別が BULK である必要があります。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"delivery_id": 1
}

配信先アドレス登録

指定した配信IDの配信種別が BULK、配信ステータスが EDIT の場合に配信先アドレスを新規に登録します。

※発行されたIDは照会、変更および削除の操作を行う際に必要になります。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Request Body schema: application/json

email required	string [ 6 .. 254 ] characters 配信先アドレス
	Array of objects or null <= 50 items 差し込みコード

Responses

Request samples

Payload

Content type

application/json

{"email": "sample_1@example.jp",
"insert_code": [{"key": "__code1__",
"value": "差し込みコードサンプル1"
},
{"key": "__code2__",
"value": "差し込みコードサンプル2"
}
]
}

Response samples

201
400
401
500

Content type

application/json

{"email_id": 1
}

配信先アドレス詳細

※配信の保管期限があります。ご注意ください。

path Parameters

email_id

required

integer <int64>

Example: 1

EメールID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"email_id": 1,
"email": "sample_1@example.jp",
"delivery_id": 161,
"insert_code": [{"key": "__code1__",
"value": "差し込みコードサンプル1"
},
{"key": "__code2__",
"value": "差し込みコードサンプル2"
}
],
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
}

配信先アドレス更新

指定したEメールIDを設定している配信IDの配信種別が BULK、配信ステータスが EDIT の場合に情報を更新します。

path Parameters

email_id

required

integer <int64>

Example: 1

EメールID

header Parameters

Authorization

required

string

認証トークン

Request Body schema: application/json

email	string [ 6 .. 254 ] characters 配信先アドレス
	Array of objects <= 50 items 差し込みコード

Responses

Request samples

Payload

Content type

application/json

{"email": "sample_1@example.jp",
"insert_code": [{"key": "__code1__",
"value": "差し込みコードサンプル1"
},
{"key": "__code2__",
"value": "差し込みコードサンプル2"
}
]
}

Response samples

200
400
401
500

Content type

application/json

{"email_id": 1
}

配信先アドレス削除

指定したEメールIDを設定している配信IDの配信種別が BULK、配信ステータスが EDIT の場合に情報を削除します。

path Parameters

email_id

required

integer <int64>

Example: 1

EメールID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"email_id": 1
}

配信先アドレス一括登録ジョブの開始

指定した配信IDの配信種別が BULK、配信ステータスが EDIT の場合に配信先アドレスを新規に登録します。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Request Body schema: multipart/form-data

file

required

string <binary> <= 256MB

text/csv 形式 / csvサンプルファイル(Download)

※一括登録用ファイルは以下の内容でアップロードをしてください。

使用可能なファイル: .csv のみ
ヘッダー1項目め: email(サンプルファイル参照)
文字コード: UTF-8
BOMなし
差し込みコードの設定上限は50件

data

string <binary>

json形式 / jsonサンプルファイル(Download)

※jsonファイルは以下の内容でアップロードをしてください。

使用可能なファイル: .json のみ
指定可能パラメータは以下の通り
- ignore_errors 除外登録フラグ
  - boolean
    Default: false
    trueの場合、fileデータにバリデーションエラーが存在した際にエラー行を除き一括登録を行います。
- immediate 即時配信フラグ
  - boolean
    Default: false
    trueの場合、配信先アドレス一括登録が完了し次第即時配信を行います。

Responses

Response samples

200
400
401
500

Content type

application/json

{"job_id": 1
}

配信先アドレス一括登録ジョブの取得

path Parameters

job_id

required

integer <int64>

Example: 1

ジョブID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"percentage": 100,
"status": "FINISHED",
"success_count": 100,
"failed_count": 120,
"total_count": 220,
"error_file_url": "https://app.engn.jp/api/v1/deliveries/-/xxx/xxx"
}

配信先アドレス一括登録エラーCSVダウンロード

ジョブ実行により形式チェックなどで失敗した配信先アドレス情報を取得します。

path Parameters

job_id

required

integer <int64>

Example: 1

ジョブID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

400
401
500

Content type

application/json

{"error_messages": {"main": ["Error Message"
]
}
}

メール解析レポートCSV生成ジョブの開始

ダウンロード項目は以下です。

配信ID
配信日時
メールアドレス
開封日時

※配信の保管期限があります。ご注意ください。

path Parameters

delivery_id

required

integer <int64>

Example: 1

配信ID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

201
400
401
500

Content type

application/json

{"job_id": 1
}

メール解析レポートCSV生成ジョブの取得

path Parameters

job_id

required

integer <int64>

Example: 1

ジョブID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"percentage": 100,
"status": "FINISHED",
"total_count": 220,
"mail_open_file_url": "https://app.engn.jp/api/v1/deliveries/-/xxx/xxx"
}

メール解析レポートCSVダウンロード

ジョブ実行により生成されたメール解析レポートを取得します。

path Parameters

job_id

required

integer <int64>

Example: 1

ジョブID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

400
401
500

Content type

application/json

{"error_messages": {"main": ["Error Message"
]
}
}

logs

配信ログ一覧

anchorで指定した値の配信ログIDを基準に、指定した値未満の配信結果を返却します。
※配信ログIDはメール1通1通のIDです。配信ID1件に対して、宛先やcc、bccごとに実際のメール通数分、配信ログIDが採番されます。
※配信の保管期限があります。ご注意ください。

query Parameters

anchor	integer >= 1 Default: "最新の配信ログID" 指定した値の配信ログIDを基準に、指定した値未満の配信結果を返却します。
count	integer [ 1 .. 1000 ] Default: 100 取得件数
email	string <= 254 characters Email(完全一致)
delivery_type[]	Array of strings <= 10 items Example: delivery_type[]=TRANSACTION&delivery_type[]=BULK 配信種別(TRANSACTION \| BULK \| SMTP)
delivery_id	integer <int64> 配信ID
status[]	Array of strings <= 10 items Example: status[]=SENT&status[]=HARDERROR 最終送信ステータス(SENT \| RETRY \| HARDERROR \| SOFTERROR \| DROP \| ALL)
response_code[]	Array of strings <= 30 items Example: response_code[]=250&response_code[]=550 レスポンスコード
delivery_start	string yyyy-MM-ddTHH:mm:ss+09:00 配信日時(開始位置) ISO 8601拡張形式のdate-time値
delivery_end	string yyyy-MM-ddTHH:mm:ss+09:00 配信日時(終了位置) ISO 8601拡張形式のdate-time値

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"data": [{"delivery_time": "2021-11-11T00:00:00+09:00",
"delivery_id": 162,
"maillog_id": 190,
"delivery_type": "BULK",
"email": "sample_1@example.jp",
"status": "HARDERROR",
"last_response_code": "550",
"last_response_message": "宛先のメールアドレスがありません。",
"open_time": "2021-11-11T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
},
{"delivery_time": "2021-11-10T00:00:00+09:00",
"delivery_id": null,
"maillog_id": 189,
"delivery_type": "SMTP",
"email": "sample_2@example.jp",
"status": "SENT",
"last_response_code": "250",
"last_response_message": "",
"open_time": "2021-11-11T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
},
{"delivery_time": "2021-11-10T00:00:00+09:00",
"delivery_id": 161,
"maillog_id": 188,
"delivery_type": "TRANSACTION",
"email": "sample_3@example.jp",
"status": "SOFTERROR",
"last_response_code": "421",
"last_response_message": "宛先サーバから一時的に拒否されました。",
"open_time": "2021-11-11T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
},
{"delivery_time": "2021-11-10T00:00:00+09:00",
"delivery_id": 160,
"maillog_id": 187,
"delivery_type": "BULK",
"email": "sample_4@example.jp",
"status": "SENDING",
"last_response_code": "",
"last_response_message": "",
"open_time": "2021-11-11T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
},
{"delivery_time": "2021-11-09T00:00:00+09:00",
"delivery_id": 159,
"maillog_id": 186,
"delivery_type": "TRANSACTION",
"email": "sample_5@example.jp",
"status": "DROP",
"last_response_code": "554(errors)",
"last_response_message": "エラー停止リストに含まれる宛先であるため、配信がドロップされました",
"open_time": "2021-11-11T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
}
]
}

配信ログ詳細

※配信の保管期限があります。ご注意ください。

path Parameters

maillog_id

required

integer <int64>

Example: 1

配信ログID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"delivery_time": "2021-11-11T00:00:00+09:00",
"delivery_id": 162,
"maillog_id": 190,
"delivery_type": "BULK",
"email": "sample_1@example.jp",
"status": "HARDERROR",
"last_response_code": 550,
"last_response_message": "宛先のメールアドレスがありません。",
"open_time": "2021-11-11T00:00:00+09:00",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00",
"sent_history": [{"status": "SENT",
"delivery_time": "2021-11-11T00:00:00+09:00",
"response_code": 250,
"response_message": "配信に成功しました。"
},
{"status": "HARDERROR",
"delivery_time": "2021-11-11T00:00:00+09:00",
"response_code": 550,
"response_message": "宛先のメールアドレスがありません。"
},
{"status": "HARDERROR",
"delivery_time": "2021-11-11T00:00:00+09:00",
"response_code": 550,
"response_message": "宛先のメールアドレスがありません。"
}
]
}

errors

エラー停止CSV生成ジョブの開始

ダウンロード項目は以下です。

配信停止番号
登録日時
メールアドレス
応答コード
エラーメッセージ

header Parameters

Authorization

required

string

認証トークン

Request Body schema: application/json

error_start	string yyyy-MM-ddTHH:mm:ss+09:00 エラー停止日時(開始日) ISO 8601拡張形式のdate-time値
error_end	string yyyy-MM-ddTHH:mm:ss+09:00 エラー停止日時(終了日) ISO 8601拡張形式のdate-time値
email	string <= 254 characters Email(正規表現不可, 完全一致)
response_code	Array of strings <= 30 items レスポンスコード

Responses

Request samples

Payload

Content type

application/json

{"error_start": "2021-01-01T00:00:00+09:00",
"error_end": "2021-01-01T23:59:59+09:00",
"email": "sample@example.jp",
"response_code": [250
]
}

Response samples

201
400
401
500

Content type

application/json

{"job_id": 1
}

エラー停止CSV生成ジョブの取得

path Parameters

job_id

required

integer <int64>

Example: 1

ジョブID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"percentage": 100,
"status": "FINISHED",
"total_count": 220,
"error_file_url": "https://app.engn.jp/api/v1/errors/xxx/xxx/xxx"
}

エラー停止CSVダウンロード

ジョブ実行により生成されたエラー停止リストを取得します。

path Parameters

job_id

required

integer <int64>

Example: 1

ジョブID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

400
401
500

Content type

application/json

{"error_messages": {"main": ["Error Message"
]
}
}

signatures

署名一覧

query Parameters

selector	string <= 100 characters セレクタ(正規表現不可, 部分一致)
domain	string <= 100 characters ドメイン(正規表現不可, 部分一致)
size	integer [ 1 .. 1000 ] Default: 100 1ページ辺りの要素数
page	integer [ 1 .. 1000 ] Default: 1 取得するページ数 (1 indexed)
sort	string Default: "created_time:desc" 並び替え条件カンマ区切りにより複数指定可 (指定可能なソート = created_time:[asc\|desc], updated_time:[asc\|desc])

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"data": [{"data": [{"signature_id": 1,
"selector": "default1",
"domain": "example.com",
"fqdn": "default1._domainkey.example.com",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
},
{"signature_id": 2,
"selector": "default2",
"domain": "example.com",
"fqdn": "default2._domainkey.example.com",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
},
{"signature_id": 3,
"selector": "default3",
"domain": "example.com",
"fqdn": "default3._domainkey.example.com",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
},
{"signature_id": 4,
"selector": "default4",
"domain": "example.com",
"fqdn": "default4._domainkey.example.com",
"created_time": "2021-01-01T00:00:00+09:00",
"updated_time": "2021-01-01T00:00:00+09:00"
}
]
}
]
}

署名登録

ご利用中のメールサーバで既に設定しているものを利用される場合は、対応する秘密鍵をご登録ください。

header Parameters

Authorization

required

string

認証トークン

Request Body schema: application/json

selector required	string [ 1 .. 100 ] characters セレクタ
domain required	string [ 1 .. 100 ] characters ドメイン
private_key required	string non-empty 秘密鍵(PKCS#8形式の 1024bit または 2048bit)

Responses

Request samples

Payload

Content type

application/json

{"selector": "default",
"domain": "example.com",
"private_key": "-----BEGIN PRIVATE KEY-----\nXXXXXXXXXXXXXXX\n-----END PRIVATE KEY-----"
}

Response samples

201
400
401
500

Content type

application/json

{"signature_id": 1
}

署名更新

path Parameters

signature_id

required

integer

Example: 1

署名ID

header Parameters

Authorization

required

string

認証トークン

Request Body schema: application/json

selector required	string [ 1 .. 100 ] characters セレクタ
private_key required	string non-empty 秘密鍵(PKCS#8形式の 1024bit または 2048bit)

Responses

Request samples

Payload

Content type

application/json

{"selector": "default",
"private_key": "-----BEGIN PRIVATE KEY-----\nXXXXXXXXXXXXXXX\n-----END PRIVATE KEY-----"
}

Response samples

200
400
401
500

Content type

application/json

{"signature_id": 1
}

署名削除

path Parameters

signature_id

required

integer

Example: 1

署名ID

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"signature_id": 1
}

usages

利用状況一覧

query Parameters

month_ago

integer <= 24

履歴月
デフォルトではリクエスト月の情報のみを返却します。
ex)2021年11月時点で3を指定した場合、2021年9～11月の3か月分が取得対象になります。

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"data": [{"month": 202111,
"current": 50000,
"remaining": 250000,
"updated_time": "2021-11-01T01:00:00+09:00",
"plan_id": "be-plan-300000"
},
{"month": 202110,
"current": 99000,
"remaining": 1000,
"updated_time": "2021-10-01T01:00:00+09:00",
"plan_id": "be-plan-100000"
},
{"month": 202109,
"current": 49900,
"remaining": 100,
"updated_time": "2021-09-01T01:00:00+09:00",
"plan_id": "be-plan-50000"
}
]
}

利用状況詳細

path Parameters

month

required

integer = 6 characters

Example: 202111

年月

header Parameters

Authorization

required

string

認証トークン

Responses

Response samples

200
400
401
500

Content type

application/json

{"month": 202111,
"current": 50000,
"remaining": 250000,
"updated_time": "2021-11-01T01:00:00+09:00",
"plan_id": "be-plan-300000"
}

API更新履歴

1.10.0(更新日: 2023/09/06)

配信ログ詳細APIを追加しました。

1.7.0(更新日: 2023/05/31)

配信先アドレス一括登録が完了し次第即時配信を行うためのフラグを追加しました。
配信ログ一覧APIを追加しました。

1.3.2(更新日: 2022/06/08)

即時で一斉配信可能なAPIを追加しました。

1.2.0(更新日: 2022/04/06)

DKIM作成者署名に関するAPIを追加しました。
一部APIでHTTPステータスコードの表記を修正しました。

blastengine API (1.10.0)

blastengine API の利用に関して

認証について

概要

リクエストヘッダ

レスポンスヘッダ

API BearerToken

利用例

Rate Limit

配信登録上限

HTTPステータスコード

各種ステータス・種別一覧

添付ファイルのサイズ制限と種類

差し込みコードについて

差し込みコードのご利用方法

配信の保管期限について

配信が開始されてから62日経過後に、配信情報とそれに関わる配信先アドレス、配信ログ情報は全て削除されます。

エラー停止について

1つの宛先に対し2週間以内に2度以上のハードエラーが発生すると、宛先はエラー停止対象となります。期間は最大で2週間となります。

deliveries

配信一覧

query Parameters

header Parameters

Responses

Response samples

配信登録(トランザクション)

※発行されたIDは照会、変更および削除の操作を行う際に必要になります。

header Parameters

Request Body schema: application/jsonmultipart/form-dataapplication/json

Responses

Request samples

Response samples

配信登録: 開始(一斉配信)

※発行されたIDは照会、変更および削除の操作を行う際に必要になります。

header Parameters

Request Body schema: application/jsonmultipart/form-dataapplication/json

Responses

Request samples

Response samples

配信登録: 更新(一斉配信)

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

配信登録: 完了(一斉配信: 予約)

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

配信登録: 完了(一斉配信: 即時)

path Parameters

header Parameters

Responses

Response samples

配信詳細

path Parameters

header Parameters

Responses

Response samples

配信削除

path Parameters

header Parameters

Responses

Response samples

配信キャンセル

path Parameters

header Parameters

Responses

Response samples

配信先アドレス登録

※発行されたIDは照会、変更および削除の操作を行う際に必要になります。

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

配信が開始されてから`62`日経過後に、配信情報とそれに関わる配信先アドレス、配信ログ情報は`全て削除`されます。

Request Body schema:
application/json

Request Body schema:
application/json