# 通知チャネル

電話接続の手順については、「[アプリを接続する](connect-app.md)」を参照してください。

## コンソールで設定する

1. **通知** を開き、Bark、Pushover、Webhook または Mailwake アプリを選択します。
2. 以下の選択したチャンネルのフィールドに入力します。 Mailwake アプリの場合、最初に [電話をペアリングする](connect-app.md) 、次に受信するスマートフォンを選択します。
3. プレビュー、通知言語、再試行回数を選択します。再試行回数が 0 の場合は 1 回の試行が行われます。
4. 保存してから、テスト通知を明示的に送信します。スマートフォンまたは Webhook の受信者と配信結果を確認します。

設定はすべてのメールボックスに適用されます。設定を変更すると、キューに入れられた作業が既存の配信計画に従って保存されます。新しいメッセージで将来の動作を確認します。

## チャンネル構成

`/api/v1/settings/delivery` を通じてグローバル チャネルを構成し、現在の `revision` を送信します。チャネル、プレビュー、再試行回数、通知言語はすべてのメールボックスに適用されます。すべての認証情報は暗号化され、書き込み専用です。接続先が同じ場合、省略した認証情報は保存済みの値を維持します。保存済みの Bark アドレスを変更する際は、デバイスキーを再入力してください。

| チャネル   | パラメータ                                                                                                                     | 資格                                                                 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `bark`     | `bark.endpoint` 、デフォルト `https://api.day.app`                                                                             | `bark.key`                                                           |
| `pushover` | なし                                                                                                                           | `pushover.token` , `pushover.user`                                   |
| `webhook`  | HTTPS、クエリは許可されています                                                                                                | `webhook.url` および `webhook.secret` (空白以外の少なくとも 32 文字) |
| `native`   | デフォルトでは、正式な本番プッシュ配信サービス。 `MAILWAKE_RELAY_URL` でオーバーライドします。アプリ認証で電話をペアリングする | ローカルで生成され、暗号化されたアウトポスト ID                      |

パスとクエリにはルーティング認証情報が含まれる可能性があるため、Webhook URL は書き込み専用です。 `preview` は `off` または `subject` を受け入れます。 `retry_count` は 0 ～ 9 を受け入れ、デフォルトは 0 です。 `language` は [9 つのカタログ コードとその地域別別名](api.md#言語とエラーコード) を受け入れ、デフォルトは `en` になります。 Bark と Pushover では、 `subject` の件名のみが表示されます。 Webhook には構造化された送信者と件名が保持されますが、その `message` にも件名のみが含まれます。 `off` (および空の件名) は、ローカライズされた「新規メール」メッセージを使用します。タイトルは `{display name} · {folder}` のままです。 Bark は同じ切り詰められたタイトルでグループ化されます。テスト通知のテキストは変更されません。 API 入力 `sender_subject` は 400 `config_preview_invalid` を返します。サードパーティ チャネルの場合、`subject` から `off` に切り替えると、すべての保留中および失敗したレコードから送信者と件名がアトミックに削除されます。その後のエンキューも、保存されたプライバシー ポリシーに従います。ネイティブ プッシュでは、サードパーティのプレビュー設定を維持しながら、送信者と件名が常に記録されます。

Bark 履歴の保持は、メール通知とテスト通知の両方に対する Bark アプリの履歴保存設定に従います。

### Webhook ペイロード

アウトポスト は JSON 本文を含む `POST` を送信し、リダイレクトに従いません。

```json
{
  "version": 1,
  "id": "3f9c…",
  "test": false,
  "mailbox_id": "mbx_example",
  "account": "Work mailbox",
  "folder": "Clients",
  "sender": "anna@example.org",
  "subject": "Re: Q4 proposal",
  "received_at": "2026-09-28T10:32:00Z",
  "title": "Work mailbox · Clients",
  "message": "Re: Q4 proposal"
}
```

`mailbox_id` は安定したメールボックス ID です。 `account` は、エンキュー時の表示名です。 Bark、Pushover、および Webhook の通常の通知では、対応するすべての言語でタイトル `{display name} · {folder}` が使用されます。メールボックスの名前を変更または削除すると、すでにキューに入っているタスクの ID メタデータが保持されます。テスト通知では別のテキストを使用し、メールボックス フィールドを省略します。

`sender` および `subject` は、`subject` プレビューでのみ表示されます。 `title` および `message` はローカライズされており、ntfy、Gotify、および同様のサービスに転送する準備ができています。表示名とフォルダーはプレビューがオフの場合でも送信されます。通知プロバイダーとの共有に適したラベルを選択してください。

| ヘッダ                 | 意味                                                                            |
| ---------------------- | ------------------------------------------------------------------------------- |
| `X-Mailwake-Event`     | イベント ID、 `id` に等しい。再試行しても変更されないため、重複排除に使用します |
| `X-Mailwake-Timestamp` | 送信時間 (Unix 秒)                                                              |
| `X-Mailwake-Signature` | `sha256=` の後に 16 進数 `HMAC-SHA256(secret, "<timestamp>.<raw body>")`        |

定時間比較を使用して同じシークレットを持つ署名を検証し、5 分以上離れたタイムスタンプを拒否します。

```python
import hashlib, hmac, time

def verify(secret: bytes, timestamp: str, body: bytes, signature: str) -> bool:
    expected = "sha256=" + hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(timestamp)) <= 300 and hmac.compare_digest(expected, signature)
```

2xx 応答はすべて受け入れられたものとしてカウントされます。 429 と 5xx は再試行設定に従います。他のステータスの場合は試行が終了し、失敗が記録されます。

通知設定を保存すると、テストを送信せずにフィールド、アドレス、ペアリング状態、およびリビジョンが検証されます。保存後に明示的なテスト ボタンを使用します。ネイティブ テストは、プッシュ配信サービスの固定無料テスト エンドポイントを使用し、アプリ テスト クォータを共有します。通常のメール通知には、有効な Native Push の利用権が必要です。