Send API & Batch Send API

ダッシュボードでドメインを選択し、API画面でAPIキーを生成します。キー全体は生成時にのみ表示されるため、その場で保存してください。再生成すると以前のキーは置き換わります。キーはブラウザー側のコードに含めず、サーバー側で管理してください。

APIを利用できるプランが必要です。差出人には、キーにひもづくドメイン上の有効なMailLogicメールアドレスを指定し、SMTPを有効にしてパスワードを設定してください。ドメイン所有権と送信用DNSの確認も必要です。

以下のすべてのエンドポイントでAuthorization: Bearer YOUR_API_KEYを使用します。X-API-Keyにも対応しています。実行前にキーとすべての.exampleアドレスを置き換えてください。Pythonの例にはpip install httpxが必要です。

POST /v1/sendにはJSONではなくフォームデータを送信します。テキスト、HTML、または両方を指定できます。複数の宛先へ同じメールを送る場合はto_emailを繰り返し指定します。

任意：Idempotency-Keyヘッダー（1〜128文字）を指定できます。新しいメールには新しいキーを使い、再試行時は同じキー・APIキー・リクエスト内容を使ってください。完了済みのリクエストは再送・再課金せず元の結果を返します。省略すると各リクエストは別の送信として扱われます。

通常の顧客向けSend APIは、同じアカウントのすべてのAPIキーとドメインを通じて、新規SMTP送信の受け付けが1秒に1件までです。未使用枠の繰り越しはありません。間隔が短い場合はHTTP 429（send_api.rate_limit_exceeded）と秒単位の整数Retry-Afterを返します。指定時間以上待ってから、同じIdempotency-Key・APIキー・内容で同じリクエストを再試行してください。拒否によって次の枠が予約されたり待ち時間が延びたりすることはなく、完了済みリクエストの再取得は新規送信に数えません。これは宛先への配信数ではなく送信リクエストの制限です。1件のリクエストには最大100件の宛先を含められます。

# Optional: add --header "Idempotency-Key: welcome-email-001" to this command.
curl --request POST https://api.maillogic.io/v1/send \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --form-string "[email protected]" \
  --form-string "display_name=MailLogic Support" \
  --form-string "[email protected]" \
  --form-string "subject=Hello from MailLogic" \
  --form-string "text_content=Thanks for signing up."

import httpx

response = httpx.post(
    "https://api.maillogic.io/v1/send",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        # "Idempotency-Key": "welcome-email-001",  # Optional
    },
    data={
        "from_email": "[email protected]",
        "display_name": "MailLogic Support",
        "to_email": "[email protected]",
        "subject": "Hello from MailLogic",
        "text_content": "Thanks for signing up.",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

添付する場合、curlに--form "attachments=@./welcome.pdf"を追加します。Pythonではwith open("welcome.pdf", "rb") as file:でファイルを開き、そのブロック内のhttpx.postにfiles={"attachments": ("welcome.pdf", file, "application/pdf")}を渡します。

{
  "status": "success",
  "message": "Email sent from [email protected] to [email protected]",
  "message_id": "[email protected]",
  "from_email": "[email protected]",
  "to_email": [
    "[email protected]"
  ],
  "accepted_recipients": [
    "[email protected]"
  ],
  "rejected_recipients": [],
  "suppressed_recipients": [],
  "recipient_count": 1,
  "accepted_recipient_count": 1,
  "rejected_recipient_count": 0,
  "suppressed_recipient_count": 0
}

JSONで宛先ごとに個別のメールを非同期送信します。各宛先にemailとvariablesを指定します。必須のsubject_templateと、少なくとも一方が必要なtext_template・html_template内で{{variable_name}}を使って値を差し込みます。

次の内容をbatch.jsonとして保存します。プレビューと作成で同じファイルを使用します。

{
  "from_email": "[email protected]",
  "subject_template": "Your {{month}} invoice",
  "text_template": "Hi {{name}}, your balance is {{amount}}.",
  "html_template": "<p>Hi {{name}}, your balance is {{amount}}.</p>",
  "recipients": [
    {
      "email": "[email protected]",
      "variables": {
        "name": "Alice",
        "month": "September",
        "amount": "$42"
      }
    },
    {
      "email": "[email protected]",
      "variables": {
        "name": "Bob",
        "month": "September",
        "amount": "$18"
      }
    }
  ]
}

1. 検証とプレビュー

POST /v1/batch-send/previewはメールを送らずに内容を検証します。レスポンスには最大5件の差し込み後のプレビュー、警告、送信可能・送信抑止対象の宛先数、クォータ情報が含まれます。

curl --request POST https://api.maillogic.io/v1/batch-send/preview \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data @batch.json

2. バッチを作成

POST /v1/batch-sendには1〜128文字のIdempotency-Keyヘッダーが必要です。新しいバッチには新しいキーを使用します。同じ内容を再試行する場合は同じキーを使うと重複作成を防げます。内容が競合すると409が返ります。

curl --request POST https://api.maillogic.io/v1/batch-send \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: invoices-2026-09-001" \
  --data @batch.json

import json
import httpx

with open("batch.json", encoding="utf-8") as file:
    payload = json.load(file)

base_url = "https://api.maillogic.io/v1/batch-send"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = httpx.post(
    base_url,
    headers={**headers, "Idempotency-Key": "invoices-2026-09-001"},
    json=payload,
    timeout=30,
)
response.raise_for_status()
batch_id = response.json()["batch"]["id"]

status = httpx.get(f"{base_url}/{batch_id}", headers=headers, timeout=30)
status.raise_for_status()
print(status.json())

成功時は202 Acceptedとbatch、duplicate、quotaが返ります。batch.idを使って進捗を確認します。duplicate: trueは既存のバッチが返されたことを示します。

3. 進捗を確認

curl https://api.maillogic.io/v1/batch-send/BATCH_ID \
  --header "Authorization: Bearer YOUR_API_KEY"

BATCH_IDをbatch.idに置き換えます。GET /v1/batch-send/{batch_id}はバッチオブジェクトを直接返します。定期的に取得し、statusと送信処理件数（sent_count、failed_count、unknown_count）、配信結果（accepted_count、deferred_count、bounced_count、delivery_failed_count、pending_count、suppressed_count）を確認してください。

バッチの最大宛先数はプランによって異なります。現在の上限はダッシュボードのAPI画面で確認してください。Batch Send APIは作成時点の差出人の表示名を使用します。添付ファイルとリクエスト単位のdisplay_nameには対応していません。

開始前に送信可能な全宛先分のクレジットを予約します。不足時は一部だけ送信せず、バッチを保留します。請求画面でクレジットを購入するか、任意の自動トップアップを有効にしてください。送信抑止対象の宛先はクレジットを消費しません。

HTTPの成功レスポンスは送信受付を示し、最終的な配信完了を保証しません。Send APIではstatusと受付・拒否・送信抑止の宛先配列および件数を確認してください。partial_successは一部の宛先が拒否または送信抑止されたこと、suppressedはどの宛先にも送信されなかったことを示します。バッチの送信処理完了も、全宛先への配信完了を意味しません。

エラー時はレスポンスのdetail（メッセージ、構造化エラー、または検証エラー一覧）を確認します。認証・アクセスエラーではキーとプラン、送信権限エラーでは差出人とDNS設定、422ではフィールドとテンプレート変数を確認してください。Send APIの402では追加クレジットが必要です。支払い成功後に再試行します。バッチの409競合ではキーと内容を確認し、429ではリクエスト頻度を下げてください。

Send APIの再試行では、同じIdempotency-Key・APIキー・内容を使ってください。同じキーで内容を変更すると409 idempotency_key_conflictになります。request_in_progressまたはsubmission_recording_pendingの場合はRetry-Afterに従い、同じキーで再試行します。submission_outcome_unknownの場合は既存リクエストの結果を調査し、新しいキーで再送しないでください。保存済みの成功結果にはIdempotency-Replayed: trueが付きます。

配信結果と送信抑止についてはメール配信のトラブル解決をご覧ください。