blastengineの一斉配信（BULK）はAPIで完全に自動化できます。本記事では begin → update → commit の3ステップで一斉配信を実装する方法を、予約配信・即時配信それぞれのパターンで解説します。

前提

blastengineのアカウントとAPIキーを取得済み
BearerTokenの生成方法は公式ドキュメントを参照

BearerTokenの生成は以下の通りです。

TOKEN=$(echo -n "${LOGIN_ID}${API_KEY}" | shasum -a 256 | awk '{print $1}' | tr A-Z a-z | base64 | tr -d "\n")

以降のコード例では $TOKEN にBearerTokenが格納されている前提で進めます。

一斉配信の全体フロー

1. begin   ─ 配信IDを発行（ステータス: EDIT）
2. update  ─ 宛先・本文を登録
3. commit  ─ 配信を予約 or 即時実行（ステータス: RESERVE → SENDING → SENT）

配信キャンセルや削除もAPIで可能です。順番に見ていきましょう。

Step 1: 配信登録の開始（begin）

POST /deliveries/bulk/begin で配信IDを発行します。

curl -X POST https://app.engn.jp/api/v1/deliveries/bulk/begin \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "news@example.com",
      "name": "配信担当"
    },
    "subject": "__company__からのお知らせ",
    "text_part": "__name__様\n\nいつもご利用ありがとうございます。\n新機能のお知らせです。",
    "html_part": "<html><body><p>__name__様</p><p>いつもご利用ありがとうございます。</p></body></html>"
  }'

レスポンス

{
  "delivery_id": 123
}

この時点で配信ステータスは EDIT です。件名・本文には差し込みコード（__name__ など）が使えます。

Step 2: 宛先の登録（update）

方法A: update APIで直接登録（50件まで）

PUT /deliveries/bulk/update/{delivery_id} で宛先と差し込みコードをまとめて登録します。

curl -X PUT https://app.engn.jp/api/v1/deliveries/bulk/update/123 \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [
      {
        "email": "user1@example.jp",
        "insert_code": [
          {"key": "__name__", "value": "田中太郎"},
          {"key": "__company__", "value": "株式会社サンプル"}
        ]
      },
      {
        "email": "user2@example.jp",
        "insert_code": [
          {"key": "__name__", "value": "鈴木花子"},
          {"key": "__company__", "value": "株式会社テスト"}
        ]
      }
    ]
  }'

注意: update APIで宛先を登録すると、既存の宛先は消去されてから再登録されます。追加登録したい場合は次の方法Bを使います。

方法B: 配信先アドレス登録APIで1件ずつ追加

POST /deliveries/{delivery_id}/emails で1件ずつ追加登録できます。

curl -X POST https://app.engn.jp/api/v1/deliveries/123/emails \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user3@example.jp",
    "insert_code": [
      {"key": "__name__", "value": "佐藤次郎"},
      {"key": "__company__", "value": "株式会社ABC"}
    ]
  }'

方法C: CSV一括登録（大量配信向け）

POST /deliveries/{delivery_id}/emails/import でCSVファイルから一括登録できます。

curl -X POST https://app.engn.jp/api/v1/deliveries/123/emails/import \
  -H "Authorization: Bearer ${TOKEN}" \
  -F "file=@recipients.csv" \
  -F 'data={"ignore_errors": true};type=application/json'

CSVの形式

email,__name__,__company__
user1@example.jp,田中太郎,株式会社サンプル
user2@example.jp,鈴木花子,株式会社テスト

一括登録はジョブとして非同期実行されます。進捗は GET /deliveries/-/emails/import/{job_id} で確認できます。

curl https://app.engn.jp/api/v1/deliveries/-/emails/import/456 \
  -H "Authorization: Bearer ${TOKEN}"

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

エラーがあった場合は error_file_url からエラーCSVをダウンロードして原因を確認できます。

Step 3: 配信の実行（commit）

パターンA: 予約配信

PATCH /deliveries/bulk/commit/{delivery_id} で配信日時を指定します。

curl -X PATCH https://app.engn.jp/api/v1/deliveries/bulk/commit/123 \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation_time": "2026-03-01T10:00:00+09:00"
  }'

配信ステータスが EDIT → RESERVE に変わり、指定日時に自動で配信が開始されます。

パターンB: 即時配信

PATCH /deliveries/bulk/commit/{delivery_id}/immediate で即時実行します。

curl -X PATCH https://app.engn.jp/api/v1/deliveries/bulk/commit/123/immediate \
  -H "Authorization: Bearer ${TOKEN}"

リクエストボディは不要です。ステータスがすぐに SENDING へ遷移します。

配信状況の確認

GET /deliveries/{delivery_id} で配信の進捗を確認できます。

curl https://app.engn.jp/api/v1/deliveries/123 \
  -H "Authorization: Bearer ${TOKEN}"

{
  "delivery_id": 123,
  "status": "SENT",
  "total_count": 1000,
  "sent_count": 980,
  "drop_count": 10,
  "soft_error_count": 5,
  "hard_error_count": 5,
  "open_count": 320
}

配信キャンセル

予約済み（RESERVE / WAIT）の配信はキャンセルできます。

curl -X PATCH https://app.engn.jp/api/v1/deliveries/123/cancel \
  -H "Authorization: Bearer ${TOKEN}"

ステータスが EDIT に戻るので、内容を修正して再度 commit できます。

Pythonで一連のフローを自動化する例

import requests
import time

BASE = "https://app.engn.jp/api/v1"
TOKEN = "YOUR_BEARER_TOKEN"
HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# 1. begin
res = requests.post(f"{BASE}/deliveries/bulk/begin", headers=HEADERS, json={
    "from": {"email": "news@example.com", "name": "配信担当"},
    "subject": "__name__様へのお知らせ",
    "text_part": "__name__様\nいつもご利用ありがとうございます。",
})
delivery_id = res.json()["delivery_id"]
print(f"配信ID: {delivery_id}")

# 2. update（宛先登録）
requests.put(f"{BASE}/deliveries/bulk/update/{delivery_id}", headers=HEADERS, json={
    "to": [
        {"email": "user1@example.jp", "insert_code": [{"key": "__name__", "value": "田中太郎"}]},
        {"email": "user2@example.jp", "insert_code": [{"key": "__name__", "value": "鈴木花子"}]},
    ]
})

# 3. commit（即時配信）
requests.patch(f"{BASE}/deliveries/bulk/commit/{delivery_id}/immediate", headers=HEADERS)

# 4. 配信状況をポーリング
while True:
    res = requests.get(f"{BASE}/deliveries/{delivery_id}", headers=HEADERS)
    data = res.json()
    print(f"ステータス: {data['status']} 送信: {data.get('sent_count', 0)}/{data.get('total_count', 0)}")
    if data["status"] in ("SENT", "FAILED"):
        break
    time.sleep(10)

注意点

配信登録上限: ステータスが EDIT の配信は同時に30件まで。不要な配信は完了させるか削除してください
Rate Limit: APIは500req/min。大量の宛先登録はCSV一括登録を使いましょう
Gmail 5000通/日以上: list_unsubscribe の設定が必要です。begin時に指定できます
配信保管期限: 配信開始から62日経過で配信情報は全て削除されます

まとめ

blastengineの一斉配信APIは begin → update → commit の3ステップで構成されており、予約配信と即時配信を使い分けられます。Pythonなどからこのフローを自動化すれば、定期配信やイベントトリガーの一斉メール配信を簡単に実装できます。