Ware Send Developer Documentation

クイックスタート

最初の送信

Ware Send 導入時に提供された URL と有効な Bearer credential を使用します。

Base URL

例では https://mail.example.jp を使用します。実際のインストールで設定された FQDN に置き換えてください。

cURL

curl -X POST "https://mail.seudominio.com.br/api/v1/send" \
  -H "Authorization: Bearer $WARESEND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_name": "Minha Empresa",
    "from_email": "notificacoes@seudominio.com.br",
    "to": ["cliente@example.com"],
    "subject": "Pedido confirmado",
    "html": "<h1>Pedido confirmado</h1>",
    "text": "Pedido confirmado"
  }'

202 Accepted

{
  "ok": true,
  "queued": true,
  "status": "accepted",
  "queue_id": "wsq_...",
  "message_id": "<...@mail.seudominio.com.br>",
  "accepted_at": "2026-08-24T03:00:00Z",
  "cost_class": "tiny",
  "version": "1.3.3"
}

accepted とは？

Ware Send は処理を検証して永続キューに保存し、その処理責任を引き受けています。受信側サーバーがすでに配信を確認したという意味ではありません。

認証

Bearer token

保護された endpoint では HTTP Authorization ヘッダーに credential が必要です。

HTTP Header

Authorization: Bearer <TOKEN>

バックエンドで使用

credential を公開 JavaScript、配布アプリ、エンドユーザーが閲覧できるソースコードに含めないでください。

Credential の受け取り

Bearer credential は、integration 導入時に指定された技術担当者または developer に、安全なチャネルと一度限りの表示で提供されます。

新しい token が必要ですか？

DB Ware または Ware Send installation の認可された担当者へ新しい credential を依頼してください。以前の token は復元できません。切り替え後は古い credential を revoke してください。

ENDPOINTS

クイックリファレンス

POST/api/v1/send

非同期処理のためにメッセージを受け取り永続化します。

Bearer

GET/api/v1/info

インストール済み Engine が公開する機能と制限を返します。

Bearer

GET/api/v1/messages/status?message_id=...

受け付け済みメッセージの既知の状態を照会します。

Bearer

GET/api/v1/engine/status

Engine、キュー、リソース、キャンペーンの運用 snapshot。

Bearer

GET/api/v1/engine/activity

実行中の処理と最近の Engine イベント。

Bearer

GET/api/v1/engine/analytics

スループット、キュー、リソース、スケジューラ、ドメイン、キャンペーンの時系列および運用集計。

Bearer

GET/health

サービスの基本状態。

公開

GET/ready

ライセンス、キュー、Postfix、DKIM の運用準備状態。

公開

メッセージ送信

メッセージを送信

UTF-8 JSON を /api/v1/send に送信します。API は検証・永続化し、非同期で応答します。

POST/api/v1/sendBearer

PAYLOAD

送信フィールド

以下が現在の API v1 公開契約です。

フィールド	型	必須	説明
`from_name`	string	いいえ	送信者の表示名。
`from_email`	string	はい	設定済みドメインで許可された送信者アドレス。
`to`	string \| array	いいえ	主宛先。1件のメールアドレスを文字列、または複数件を配列で指定できます。
`cc`	string \| array	いいえ	CC 宛先。文字列または配列を指定できます。
`bcc`	string \| array	いいえ	BCC 宛先。文字列または配列を指定でき、表示ヘッダーには一切露出しません。
`to_visible`	boolean	いいえ	受信者の表示可否を制御します。任意、既定値 false。false は各受信者を分離し、true の場合のみ To/Cc の共有表示を許可します。Bcc は常に非表示です。
`reply_to`	string	いいえ	任意の Reply-To アドレス。
`subject`	string	はい	件名。
`html`	string	いいえ	HTML 本文。
`text`	string	いいえ	プレーンテキスト本文。
`tenant`	string	いいえ	アプリケーション、顧客、統合コンテキストの論理識別子。
`campaign_id`	string	いいえ	キャンペーンの運用アクティビティをグループ化する論理識別子。
`campaign_report_email`	string	いいえ	キャンペーン完了レポートの送信先となる任意のメールアドレス。campaign_id が必須となり、そのキャンペーン状態が存在する間は送信先が紐づきます。
`idempotency_key`	string	いいえ	同じリクエストの誤再送を防ぐ安定したキー。
`headers`	object	いいえ	追加の非予約ヘッダー。メールの構造ヘッダーは Engine が管理します。
`attachments`	array	いいえ	通常または inline/CID 添付。

* to、cc、bcc のいずれかに最低1宛先、html と text のいずれかに最低1本文が必要です。HTTP API の to/cc/bcc は文字列または配列を受け付け、アプリケーションレベルの論理的な宛先数上限はありません。実際にはリクエストサイズとホスト資源が上限になります。SMTP Submission には独立した上限があり、GET /api/v1/info で確認できます。

RECIPIENT PRIVACY

複数宛先でも既定でプライベート

API の宛先リストは Engine のルーティング入力です。1つの payload に多数のアドレスを指定しても、Ware Send がその一覧を受信者へ公開する許可にはなりません。

Default · to_visible=false

{
  "to": [
    "empresa-a@example.com",
    "empresa-b@example.com",
    "empresa-c@example.com"
  ],
  "subject": "Comunicado",
  "html": "<p>Olá</p>"
}

安全な既定値: to_visible = false

to_visible を省略するか false にすると、Engine が内部で fan-out を行い、受信者ごとに個別配送を生成します。受信メールの To: には本人のアドレスだけが表示され、他の to、cc、bcc は表示されません。

Explicit opt-in · to_visible=true

{
  "to": ["a@example.com", "b@example.com"],
  "cc": ["c@example.com"],
  "to_visible": true,
  "subject": "Reunião compartilhada",
  "text": "Mensagem"
}

表示には明示的な opt-in が必要

to_visible:true を明示した場合のみ、request の To と Cc を表示ヘッダーにまとめて出すことができます。参加者同士が他のアドレスを知ってよい場合にだけ使用してください。

Bcc は常に非表示

Bcc は envelope の宛先としてのみ保持されます。to_visible=true の場合でも、Engine は表示可能な Bcc ヘッダーを出力しません。

fan-out は Engine の責務

HTTP API にはアプリケーションレベルの論理的な宛先数上限がありません。Engine が受理した集合を内部で分割・処理します。リクエストサイズとホスト資源が実際上の制約で、SMTP Submission には独立した上限があります。

Job と受信者は別のメトリクス

多数のアドレスを含む request も論理的には1 jobですが、複数の受信者を持ちます。受信者数は accepted_recipients_total と postfix_queued_recipients_total、job 数は accepted_total と postfix_queued_total を参照してください。

添付

添付ファイルと inline 画像

API v1 は Base64 添付との互換性を維持しています。受理後、Engine は内容を Blob として永続化し、非同期に処理します。

通常添付

{
  "filename": "fatura.pdf",
  "content_type": "application/pdf",
  "content_base64": "JVBERi0xLjQK..."
}

Inline 画像 / CID

{
  "html": "<img src=\"cid:logo_empresa\" alt=\"Logo\">",
  "attachments": [{
    "filename": "logo.png",
    "content_type": "image/png",
    "content_base64": "iVBORw0KGgoAAA...",
    "cid": "logo_empresa",
    "inline": true
  }]
}

主なルール

各添付には filename と content_base64 が必要です。inline 添付には有効な cid と HTML 本文が必要です。同じメッセージ内の重複 CID は拒否されます。

信頼性

冪等性とキャンペーン

idempotency_key

論理イベントごとに予測可能なキーを使用します。同じリクエストがすでに受理されている場合、Ware Send は新しい処理を作成せず duplicate: true と以前の参照を返すことがあります。

campaign_id

大規模キャンペーンの運用アクティビティをグループ化し、Engine snapshot で受理、処理、retry、失敗を追跡できます。

campaign_report_email

campaign_report_email を campaign_id に紐づけると、完了要約と詳細 HTML レポートを自動受信できます。

冪等性処理中

同じキーの別リクエストがまだ統合処理中の場合、API は 409 Conflict を返すことがあります。待機して照会するか、同じキーで再送してください。

キャンペーン完了

キャンペーン完了レポート

campaign_report_email と campaign_id を指定すると、Ware Send はキャンペーンを Engine の終端状態まで追跡し、スタイル付き HTML 要約と詳細 HTML 添付を送信します。

POST /api/v1/send

{
  "tenant": "erp-production",
  "campaign_id": "invoice-batch-2026-08-26",
  "campaign_report_email": "mail-ops@example.com",
  "from_email": "billing@example.com",
  "to": ["customer@example.net"],
  "subject": "Invoice",
  "text": "Your invoice is attached."
}

202 Accepted

{
  "ok": true,
  "status": "accepted",
  "message_id": "wsm_...",
  "campaign_report_requested": true,
  "version": "1.3.3"
}

フィールドルール

任意フィールドですが、指定時は campaign_id が必要です。同じ campaign_id の送信先を状態存続中に黙って変更できません。論理キャンペーンごとに一意の ID を使用してください。

発行タイミング

受理済み job がすべて POSTFIX_QUEUED または Engine 終端エラーとなり、設定された quiet period（既定 60 秒）に新規受理がない場合に発行します。後続 job により新しい revision が作られる場合があります。

証明する範囲

Ware Send の完了とローカル Postfix への handoff（利用可能なら Queue-ID）を証明します。Inbox 到達証明ではなく、remote delivery/defer/bounce には MTA/DSN 証跡が必要です。

顧客が受け取る内容

メール本文に要約、添付 HTML に campaign/tenant、job、宛先、bytes、Postfix handoff、エラー、retry、Queue-ID、domain 分布、revision を記録します。秘密情報や本文は含めません。

可観測性

メッセージと Engine の状態

以下の endpoint により VPS へ直接アクセスせず実行状況を確認できます。

GET/api/v1/messages/status?message_id=...Bearer

指定したメッセージの最新の既知状態を返します。

例

{
  "ok": true,
  "message_id": "<...@mail.seudominio.com.br>",
  "queue_id": "wsq_...",
  "state": "POSTFIX_QUEUED",
  "stage": "POSTFIX_OWNS_MESSAGE",
  "postfix_queue_id": "4ABC123DEF",
  "cost_class": "tiny",
  "recipients": 1,
  "attempts": 0,
  "version": "1.3.3"
}

GET/api/v1/engine/statusBearer

Engine の広範な snapshot：backlog、worker、入出力レート、リソース、Postfix キュー、Adaptive 状態、最近の活動、キャンペーン。

GET/api/v1/engine/activityBearer

頻繁な監視向けの簡易表示：Adaptive 状態、保留、実行中 job、最近のイベント、throughput。

GET/api/v1/engine/analyticsBearer

スループット、キュー、リソース、スケジューラ、ドメイン、キャンペーンの時系列および運用集計。

ACCEPTEDQUEUEDMATERIALIZINGPOSTFIX_QUEUED

現在の API v1 は Postfix が受理するまでの Ware Send の責任を正確に追跡します。宛先ごとの最終確認、DSN/bounce、リモート配信状態は公開契約に含まれた時点で文書化します。

HTTP

レスポンスとエラー

HTTP	意味	推奨対応
202	メッセージを受理し永続化しました。	処理を追跡する場合は message_id と queue_id を保存してください。
200	照会成功、またはすでに受理済みの冪等送信。	重複時は duplicate: true を確認してください。
400	JSON またはフィールドが不正です。	payload を修正してください。未知のフィールドも拒否されます。
401	Credential がない、無効、または revoke 済みです。	アプリケーションに設定された Bearer token を確認してください。
403	インストールに有効な運用ライセンスがありません。	Ware Send インストール管理者に連絡してください。
409	冪等性キーがすでに処理中です。	待ってから同じキーで再試行してください。
503	キュー利用不可、または一時的な backpressure。	Retry-After がある場合は従い、backoff を使って再試行してください。

認証エラー

{
  "ok": false,
  "error": "unauthorized"
}

レガシーシステム

SMTP Submission

HTTP API を利用できないレガシーシステム向けに、Ware Send は認証付き SMTP Submission を提供します。SMTP は API と同じ Engine、キュー、scheduler、worker、Postfix を使用し、別の配信 pipeline は作りません。

Engine 1.0.0 で利用可能

SMTP Submission は認証されたアプリケーション入力専用です。MX inbound、mailbox、POP3、IMAP、webmail ではありません。ポート 25 は引き続き MTA/Postfix の役割です。

SMTPmail.seudominio.com.br:587 / :465TLS + AUTH

インストール先の FQDN を使用し、587 + STARTTLS または 465 + 暗黙的 TLS を選択します。認証は必須で、API とは独立したインストール単位の共通 SMTP パスワードを使用します。顧客ドメインから生成した正規アドレス（例: example@example.jp）は既定の ID にすぎず、同じパスワードで contact@example.jp、billing@example.jp、nfe@example.jp など同一ドメイン内の任意の完全なメールアドレスを認証できます。正規 ID の短い別名（example）は AUTH の互換用としてのみ使用できます。他ドメインは拒否され、MAIL FROM は引き続き許可済み送信ドメインの制約を受けます。API の Bearer token は SMTP 認証には使用できません。

サーバー	`mail.seudominio.com.br`
ポート	`587` / `465`
セキュリティ	`STARTTLS` / `implicit TLS`
認証	`AUTH PLAIN` / `AUTH LOGIN`
ユーザー名	`example@example.com`
パスワード	導入またはローテーション時に提供される専用 SMTP パスワード。API の ws_live_ Bearer token は使用しないでください。

両方のポートで TLS が必須です

587 では SMTP 接続後、AUTH の前に STARTTLS をネゴシエートします。465 では接続開始直後から TLS を使用します。Ware Send は暗号化されていない SMTP 認証を受け付けません。

SMTP フロー

# Porta 587 / STARTTLS
S: 220 mail.seudominio.com.br ESMTP Ware Send 1.0.0
C: EHLO legado.local
S: 250-STARTTLS
C: STARTTLS
   ... TLS handshake ...
C: EHLO legado.local
S: 250-AUTH PLAIN LOGIN
C: AUTH ...
S: 235 2.7.0 Authentication successful
C: MAIL FROM:<notificacoes@seudominio.com.br>
S: 250 2.1.0 Sender OK
C: RCPT TO:<cliente@example.com>
S: 250 2.1.5 Recipient OK
C: DATA
S: 354 End data with <CR><LF>.<CR><LF>
C: ... RFC 5322 / MIME ...
C: .
S: 250 2.0.0 Message accepted for delivery; queue_id=wsq_...

250 の意味

DATA 完了後、Ware Send は処理を永続キューへ保存した後にのみ 250 を返します。これは HTTP 202 Accepted と同様に処理責任を引き受けたことを意味し、受信者への最終配信完了を意味しません。

制限と宛先

SMTP は Engine に設定された API と同じメッセージサイズ・宛先数の制限を使用します。GET /api/v1/info で確認できます。複数の RCPT TO と、1 セッションでの複数メッセージ送信をサポートします。

BCC と MIME

RFC 5322/MIME 内容は保持されます。BCC 宛先は RCPT TO envelope に含めてください。レガシークライアントが Bcc または Resent-Bcc header も送信した場合、Ware Send は漏えい防止のため配信前にその header を削除します。

任意メタデータ

SMTP クライアントは X-WareSend-Tenant と X-WareSend-Campaign-ID header を送信し、運用コンテキストやキャンペーンへ関連付けできます。

SMTP の冪等性

API の idempotency_key セマンティクスは SMTP 1.0.0 では提供されません。DATA 後、250 を受け取る前に接続が切れた場合、クライアント側では受理結果が不明確になることがあります。Message-ID による自動重複排除を前提にしないでください。

API と同じ dataplane

受理後は API と SMTP が同じキューと配信経路を使用します。SMTP 固有の egress 上限はありません。数値的な throughput はインストール環境の benchmark と SMTP クライアントの動作に依存します。

GET/api/v1/infoBearer

GET /api/v1/info では SMTP Submission の有効状態、ホスト、既定ユーザー名、auth_domain、username_policy、パスワード設定有無、587/STARTTLS、465/暗黙的 TLS、AUTH メカニズムを確認できます。

設定の確認

{
  "supports_smtp_submission": true,
  "smtp_submission": {
    "enabled": true,
    "host": "mail.seudominio.com.br",
    "username": "seudominio@seudominio.com.br",
    "auth_domain": "seudominio.com.br",
    "username_policy": "any-mailbox-in-auth-domain",
    "auth_configured": true,
    "auth_mechanisms": ["PLAIN", "LOGIN"],
    "starttls": {"enabled": true, "port": 587, "required": true},
    "implicit_tls": {"enabled": true, "port": 465}
  }
}

WARE SEND

シンプルな統合。Engine が運用を制御。

アプリケーションがメッセージを送信すると、Ware Send が永続化、キュー、Adaptive 制御、インフラ容量に応じた MTA への引き渡しを担当します。

Ware Send に戻る