API の利用には、blastengineのサービス利用規約が適用され、API を利用すると同利用規約に同意したものとみなされます。
APIキー発行時に作成される BearerToken を Authorization
ヘッダにセットしてリクエストをサーバーに発行することでAPIを利用できます。 BearerToken はユーザごとに異なりますので、 BearerToken を使うことでそのユーザのアクセス権を保持しているということになります。
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 を利用して以下のようなリクエストをサーバーに発行します。
[BearerToken]には作成した BearerToken を入れてください。
curl https://app.engn.jp/api/v1/XXXXX -H "Authorization: Bearer [BearerToken]"
※ API BearerToken の生成方法
下記に記載する手順で生成してください。
[前提] API BearerToken の生成には apiKey
が必要です。
apiKeyの発行・再発行は管理画面上から行ってください。
echo -n 'ログインID + apikey' | shasum -a 256
出力された文字列を全て小文字化します
echo -n '小文字化した文字列' | base64
以下の例をご利用の場合、記載の順にAPIを実施してください。
・利用例A
:トランザクション配信
・利用例B
:一斉配信
発行した配信IDに対して、以下のいずれかを利用して配信先アドレスを登録します。
配信登録: 完了(一斉配信) API で配信予約日時の登録をします。
配信予約日時経過後の配信状況は配信詳細 APIの配信ステータスをご確認ください。
※配信数によっては全てのメール配信処理完了までに時間がかかる可能性があります。
・利用例C
:配信先アドレス一括登録
Rate Limitは500req/mでございます。 blastengine APIには、サーバー負荷を抑える目的で 呼び出し回数制限 の仕組みが実装されています。 1分間に500回を超えた場合は リクエスト数制限超過エラーになります。 ※呼び出し回数制限値は予告なく変更する場合がございます。
blastengine APIで登録できる配信の数には上限がございます。 配信ステータスがEDITの配信が30件になりますと、それ以上配信登録ができなくなります。 追加で配信登録を行う場合、EDITの配信を完了させるか、削除する必要がございます。
コード | 種別 | 説明 |
---|---|---|
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配信 |
配信ステータス
ステータス | 説明 |
---|---|
EDIT | 編集中 |
IMPORTING | 配信アドレス一括インポート中 |
RESERVE | 配信予約済 |
WAIT | 配信待ち |
SENDING | 配信中 |
SENT | 配信成功 |
FAILED | 配信失敗 |
最終送信ステータス
ステータス | 説明 |
---|---|
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(relay) | 転送先メールサーバでエラーが発生しました |
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 | ブラストエンジン |
本文差し込みイメージ
__prop1__ 様
(会員番号 __prop2__)
__prop3__ をご利用いただきありがとうございます。
テスト太郎 様
(会員番号 123456)
ブラストエンジン をご利用いただきありがとうございます。
※配信の保管期限 があります。ご注意ください。
text_part | string <= 300 characters テキストパート(正規表現不可, 部分一致) |
html_part | string <= 300 characters HTMLパート(正規表現不可, 部分一致) |
subject | string <= 30 characters 件名(正規表現不可, 部分一致) |
from | string <= 254 characters 送信元アドレス(正規表現不可, 部分一致) |
status[] | |
delivery_type[] | |
delivery_start | string yyyy-MM-ddTHH:mm:ss+09:00 配信日時(開始位置) |
delivery_end | string yyyy-MM-ddTHH:mm:ss+09:00 配信日時(終了位置) |
size | integer [ 1 .. 1000 ] Default: 100 1ページ辺りの要素数 |
page | integer [ 1 .. 1000 ] Default: 1 取得するページ数 (1 indexed) |
sort | string Default: "delivery_time:desc" 並び替え条件 |
Authorization required | string 認証トークン |
配信履歴と予約のリストを返却します
バリデーションエラー
システム内部エラー
Production server
Authorization required | string 認証トークン |
from required | object 送信元情報 |
to required | string [ 6 .. 254 ] characters 宛先 |
cc | Array of strings <= 10 items CC |
bcc | Array of strings <= 10 items BCC |
insert_code | Array of objects <= 50 items |
subject required | string [ 1 .. 150 ] characters 件名 |
encode | string Default: |
text_part required | string <= 30 kb テキストパート |
html_part | string <= 70 kb HTMLパート |
登録した配信IDを返却します
Production server
Authorization required | string 認証トークン |
from required | object 送信元情報 |
encode | string Default: |
subject required | string [ 1 .. 150 ] characters 件名 |
text_part required | string <= 30 kb テキストパート |
html_part | string <= 70 kb HTMLパート |
登録した配信IDを返却します
Production server
指定した配信IDの配信ステータスが EDIT の場合に情報を更新します。
delivery_id required | integer <int64> Example: 1 配信ID |
Authorization required | string 認証トークン |
from | object 送信元情報 |
to | Array of objects 宛先 (上限50件。すでに宛先が登録済みの場合、消去後に登録されます。) |
subject | string [ 1 .. 150 ] characters 件名 |
text_part | string <= 30 kb テキストパート |
html_part | string <= 70 kb HTMLパート |
更新した配信IDを返却します
Production server
指定した配信を 配信予約日時
に一斉配信します。
指定した配信IDの配信ステータスを RESERVE に更新します。
配信先アドレスが1件以上設定されている必要があります。
delivery_id required | integer <int64> Example: 1 配信ID |
Authorization required | string 認証トークン |
reservation_time required | string yyyy-MM-ddTHH:mm:ss+09:00 配信予約日時 |
配信登録が完了した配信IDを返却します
Production server
指定した配信を 即時
一斉配信します。
配信先アドレスが1件以上設定されている必要があります。
delivery_id required | integer <int64> Example: 1 配信ID |
Authorization required | string 認証トークン |
配信登録が完了した配信IDを返却します
Production server
※配信の保管期限 があります。ご注意ください。
delivery_id required | integer <int64> Example: 1 配信ID |
Authorization required | string 認証トークン |
指定の配信情報を返却します
Production server
delivery_id required | integer <int64> Example: 1 配信ID |
Authorization required | string 認証トークン |
削除した配信IDを返却します
Production server
delivery_id required | integer <int64> Example: 1 配信ID |
Authorization required | string 認証トークン |
キャンセルした配信IDを返却します
Production server
delivery_id required | integer <int64> Example: 1 配信ID |
Authorization required | string 認証トークン |
email required | string [ 6 .. 254 ] characters 配信先アドレス |
insert_code | Array of objects <= 50 items Nullable |
登録したEメールIDを返却します
Production server
※配信の保管期限 があります。ご注意ください。
email_id required | integer <int64> Example: 1 EメールID |
Authorization required | string 認証トークン |
指定の配信先アドレス情報を返却します
Production server
email_id required | integer <int64> Example: 1 EメールID |
Authorization required | string 認証トークン |
string [ 6 .. 254 ] characters 配信先アドレス | |
insert_code | Array of objects <= 50 items |
更新したEメールIDを返却します
Production server
email_id required | integer <int64> Example: 1 EメールID |
Authorization required | string 認証トークン |
削除したEメールIDを返却します
Production server
delivery_id required | integer <int64> Example: 1 配信ID |
Authorization required | string 認証トークン |
file required | string <binary> <= 256MB text/csv 形式 / csvサンプルファイル(Download) ※一括登録用ファイルは以下の内容でアップロードをしてください。
|
data | object json形式 |
登録した配信先アドレス一括登録ジョブのジョブIDを返却します
Production server
job_id required | integer <int64> Example: 1 ジョブID |
Authorization required | string 認証トークン |
配信先アドレス一括登録状況を返却します
Production server