blastengine API (1.18.1)

blastengine API の利用に関して

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

認証について

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

概要

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

項目	説明
APIのバージョン	1.12.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の配信ステータスをご確認ください。

※1 配信数によっては全てのメール配信処理完了までに時間がかかる可能性があります。  
※2 Gmail宛てに1日あたり5000通以上配信を行う場合は、list_unsubscribe を設定してください。  
    設定していない場合、メール送信者のガイドラインに違反しているとみなされ、迷惑メール判定されてしまう場合があります。

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

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

Rate Limit

Rate Limitは500req/mでございます。 blastengine APIには、サーバー負荷を抑える目的で呼び出し回数制限の仕組みが実装されています。
1分間に500回を超えた場合はリクエスト数制限超過エラーになります。
500req/m以上をご希望される場合は問い合わせフォームまでご相談ください。
エラーが発生した場合は必要に応じてエラーハンドリングとリトライ処理の実施を推奨します。
リトライ処理はレート制限の範囲内でリクエストを再送してください。
※呼び出し回数制限値は予告なく変更する場合がございます。

配信登録上限

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

List-Unsubscribe

List-Unsubscribeヘッダーを付与して配信することが可能です。

mailto: 購読解除をメールで受け取る場合
url: 購読解除をOne-Click機能で受け取る場合

mailto または url を設定する際は、DKIM（作成者署名）を設定の上、必要に応じてURLエンコードを実施してください。
mailto および urlは、データサイズ（差し込みコード有の場合、変換後のデータサイズ）が概ね980byteに収めるようにしてください。
docomoドメインに対して配信する際、制限byte数を越えていると配信できない場合があります。

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	宛先サーバから一時的に拒否されました
421(gmail-url)	本文中のいずれかのURL(ドメイン)に対する迷惑メールの疑いのため、一時的に送信レートが制限されました。本文内のURLやドメインがブラックリストに登録されていないか確認してください。
421(gmail-dmarc)	DMARCアライメントがないため、送信レートが制限されました。DMARCの設定を行う、もしくは正しく設定されていることをご確認ください。
421(gmail-ratelimit)	配信実績の少ないDKIM署名しているドメインから大量配信されたため、送信レートが制限されました。配信総数を徐々に増やすように調整してください。
421(gmail-dkim)	DKIM作成者署名の認証に失敗したため、送信レートが制限されました。DKIM作成者署名の設定を行う、もしくは正しく設定されていることをご確認ください。
450	一時的に宛先のメールボックスが利用できません
450(gmail-receivelimit)	宛先メールアドレスは、受付できない速度でメールを受信しています。しばらく時間をおいてから再度送信してください。
451	宛先サーバで一時的なエラーが発生しました
452	宛先サーバのシステムリソースが不足しています
453	宛先サーバで一時的なエラーが発生しました
454	内部処理中にエラーが発生しました
500	1行に対する文章が長すぎるため受け付けられません
521	宛先のメールボックスがいっぱいです
530	宛先サーバへの送信には認証または暗号化が必要です
550	宛先のメールアドレスがありません
550(rejection)	宛先サーバから受信拒否を受けました
551	宛先のメールアドレスがありません
552	宛先のメールボックスがいっぱいです
553	宛先のメールボックスが利用できません
554	宛先サーバでエラーが発生しました
554(banned)	配信が禁止されたアドレスへの配信のためブロックしました
554(errors)	エラー停止リストに含まれる宛先であるため、配信がドロップされました
554(rejection)	宛先が配信可能なアドレスではありません。配信可能アドレスの登録状況をご確認ください。スタートアップガイドページから配信可能アドレスを確認できます。

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

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)や件名(subject)、List-Unsubscribeヘッダの購読解除(list_unsubscribe)に設定しておくことで、メール送信時に差し込みコードのvalueへ置き換えられます。
差し込みコードの設定上限は50件です。
APIリファレンスにおいて、差し込みコードに対応しているパラメータには 差し込みコード対応 と記載しています。

差し込みコード

key __prop1__ __prop2__ __prop3__ __prop4__

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

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

__prop1__ 様    

 （会員番号 __prop2__）    

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

テスト太郎 様    

 （会員番号 123456）    

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

List-Unsubscribe 差し込みイメージ

List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe&body=__prop4__>, <https://example.com/unsubscribe/__prop4__>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe&body=012345>, <https://example.com/unsubscribe/012345>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

配信の保管期限について

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

エラー停止について

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

deliveries

配信一覧(APIのみ)

配信種別が TRANSACTION もしくは BULK である配信結果を返却します。
※SMTPの配信結果を含めて返却する際は配信一覧をご利用下さい。
※配信の保管期限があります。ご注意ください。

query Parameters

text_part	string <= 300 characters テキストパート(正規表現不可, 部分一致)
html_part	string <= 300 characters HTMLパート(正規表現不可, 部分一致)
subject	string <= 30 characters 件名(正規表現不可, 部分一致)
from	string <= 254 characters 送信元アドレス(正規表現不可, 部分一致)
list_unsubscribe_mailto	string <= 450 characters 購読解除メールアドレス(mailto URI)(正規表現不可, 部分一致)
list_unsubscribe_url	string <= 450 characters 購読解除URL(正規表現不可, 部分一致)
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": null,
"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, BULK, SMTP である配信結果を返却します。
※配信の保管期限があります。ご注意ください。

query Parameters

text_part	string <= 300 characters テキストパート(正規表現不可, 部分一致)
html_part	string <= 300 characters HTMLパート(正規表現不可, 部分一致)
subject	string <= 30 characters 件名(正規表現不可, 部分一致)
from	string <= 254 characters 送信元アドレス(正規表現不可, 部分一致)
list_unsubscribe_mailto	string <= 450 characters 購読解除メールアドレス(mailto URI)(正規表現不可, 部分一致)
list_unsubscribe_url	string <= 450 characters 購読解除URL(正規表現不可, 部分一致)
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&delivery_type[]=SMTP 配信種別(TRANSACTION \| BULK \| SMTP \| 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": null,
"delivery_type": "SMTP",
"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": null,
"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 件名差し込みコード対応
	object List-Unsubscribe
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": "テスト件名",
"list_unsubscribe": {"mailto": "mailto:unsubscribe@example.com?subject=unsubscribe&body=012345",
"url": "https://example.com/unsubscribe/012345"
},
"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 件名差し込みコード対応
	object List-Unsubscribe
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": "テスト件名",
"list_unsubscribe": {"mailto": "mailto:unsubscribe@example.com?subject=unsubscribe&body=012345",
"url": "https://example.com/unsubscribe/012345"
},
"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 件名差し込みコード対応
	object List-Unsubscribe
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": "テスト件名",
"list_unsubscribe": {"mailto": "mailto:unsubscribe@example.com?subject=unsubscribe&body=012345",
"url": "https://example.com/unsubscribe/012345"
},
"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
}

配信詳細

※配信の保管期限があります。ご注意ください。
※delivery_type: SMTPにおいて本文抽出に対応していないメール形式で送信された場合、空でtext_part, html_partをレスポンスします。

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
差し込みコードの設定上限は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": 161,
"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": 160,
"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": 159,
"maillog_id": 187,
"delivery_type": "BULK",
"email": "sample_4@example.jp",
"status": "SENT",
"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": 158,
"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": [{"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.18.1(更新日: 2024/8/15)

以下APIで件名(subject)が差し込みコードに対応しました。また、差し込みコードに対応しているパラメータに対応を明記しました。
差し込みコードについての記載に件名(subject)について明記しました。

1.18.0(更新日: 2024/7/31)

配信先アドレス一括登録ジョブの開始でリクエストに使用いただくCSVファイルについて、BOM付きを許容するように変更しました。
レスポンスコードに以下ステータスを追加しました。
- 450(gmail-receivelimit)
- 554(rejection)

1.12.0(更新日: 2023/12/18)

配信一覧にSMTPの配信結果を追加しました。
以下APIにlist_unsubscribeを追加しました。

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.18.1)

blastengine API の利用に関して

認証について

概要

リクエストヘッダ

レスポンスヘッダ

API BearerToken

利用例

Rate Limit

配信登録上限

List-Unsubscribe

HTTPステータスコード

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

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

差し込みコードについて

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

配信の保管期限について

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

エラー停止について

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

deliveries

配信一覧(APIのみ)

query Parameters

header Parameters

Responses

Response samples

配信一覧

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

配信先アドレス登録

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

Request Body schema:
application/json

Request Body schema:
application/json