受信メールの理解
Vonage Email API は、Messages API の一部として受信メールをサポートしています。Vonage によって Verify されたドメインおよびサブドメイン宛てに送信されたメールを受信し、Webhook を通じてアプリケーションに配信することができます。
メールが認証済みのドメインに届くと、Vonageはそのメールを受信して処理し、そのドメインに紐付けられたVonageアプリケーションを特定した上で、そのアプリケーションで設定されたインバウンドURLにWebhookイベントを送信します。
前提条件
受信メールの設定を行う前に、以下の条件が満たされていることを確認してください:
- Eメールチャネルへのアクセスが有効になっているVonage API Account。
- SPF、DKIM、およびDMARCが設定された、Verifyされたドメインが少なくとも1つあること。
- 認証済みのインバウンドサブドメイン。
- 「メッセージ」機能が有効になっているVonage Application。
- Vonage Applicationsにリンクされているインバウンドドメイン。
- そのアプリケーションで設定されたインバウンドWebhookのURL。
アプリケーションレベルの受信配信を行うには、ドメインリンクと受信URLが必須です。詳しくは Webhookのルーティング優先度 AccountレベルのWebhookのみが設定されている場合、どのような動作になるか。
必要な手順
受信メールについては、送信メールの認証に使用されるSPF、DKIM、DMARCレコードに加え、追加のオンボーディングおよびDNS設定が必要となります。
インバウンドDNSの設定
レコードの構造は以下の通りです:
| 目的 | タイプ | ホスト/キー | 価値 | 説明 |
|---|---|---|---|---|
| RECEIVE | CNAME | <subyourdomain> |
inbound-smtp.eu.msg.vonage.com |
インバウンドCNAMEレコード |
表示されている値はEUの例です。DNSレコードの値は地域(EU、米国、APAC)によって異なります。お住まいの地域に対してVonageが提供する正確な値を使用してください。DNSの反映には最大72時間かかる場合があります。
インバウンドドメインをVonage Applicationsにリンクする
重要だ: これは必須の前提条件です。ドメインが、受信URLが設定済みのVonage Applicationsに紐付けられていない場合、受信メールは配信されません。
の中で Vonage APIダッシュボード:
- こちらへ アプリケーション を選択する。 ドメインをリンクする.
- Verifyされた受信ドメインをリンクしてください。
- Applicationsを開き、「メッセージ」機能が有効になっていることを確認してください。
- を設定する。 インバウンドURL 「メッセージ」機能の下に。
Vonage は、アプリケーション ID を使用して、着信 Webhook イベントをどこにルーティングするかを決定します。アプリケーションレベルの着信 URL は、Account レベルの着信 Webhook よりも優先されます。1 つのアプリケーションに複数のドメインを紐付けることができ、各アプリケーションは、そのアプリケーションに紐付けられたドメインに関する着信イベントのみを受信します。
インバウンド・オンボーディング
オンボーディング時のDNS設定
アカウントマネージャーに以下の情報を提供してください:
- 次のようなインバウンドサブドメインのプレフィックス、例えば
reply,inboundあるいはsupport. - ルートVerify済みドメイン。
Vonage は、お客様の地域に対応した DNS レコードの値を生成します。提供された内容とまったく同じ形で、そのレコードを DNS プロバイダーに追加してください。Vonage は、レコードの反映が完了したことを Verify してから、着信受信機能を有効にします。
ドメイン認証
Vonage がそのドメイン宛てにメールを転送するには、まずその受信ドメインの Verify を行う必要があります。Verify ステータスの遷移は以下の通りです:
INITIATED -> PENDING_VERIFICATION -> VERIFIED
-> FAILED_VERIFICATION
72時間経過しても確認が完了しない場合は、担当のAccountマネージャーにご連絡いただくか、サポートチケットをご提出ください。
サブドメインとルートドメインのどちらが推奨されるか
おすすめだ: 次のような専用のサブドメインを使用してください。 reply.yourdomain.com または inbound.yourdomain.com、受信メールについては。
次のようなルートドメインを使用して、 yourdomain.com、受信側のDNSレコードによって、既存の受信メール設定が上書きされる可能性があるためです。宛先が @yourdomain.com これにより、Google Workspace、Microsoft 365、またはその他のプロバイダーがホストする企業の受信トレイ宛てのメールを含め、Vonage へ転送される可能性があります。これにより、既存の受信メールの設定が機能しなくなる可能性があります。復旧するには、DNS レコードを削除し、DNS の伝播が完了するまで待つ必要がありますが、その間、受信メールが失われる可能性があります。
サブドメインを使用することで、Vonageの着信経路を分離します。例えば、 reply.yourdomain.com は、以下のアドレスの宛先に送信されたメッセージのみを受信します。 @reply.yourdomain.com; 会社のメールアドレスは @yourdomain.com 影響を受けません。また、用途に応じて異なるサブドメインを使用することもできます:
| 使用例 | 送信元アドレス | サブドメイン |
|---|---|---|
| 返信の追跡 | reply@reply.acme.com |
reply.acme.com |
| サポートチケット | support@help.acme.com |
help.acme.com |
| お知らせ | alerts@notify.acme.com |
notify.acme.com |
注意: ルートドメインを受信メールに使用する場合は、そのドメインが送信専用であり、他のサービスがメールの受信にそのドメインに依存していない場合に限り、これを行ってください。
受信メールのフローとシナリオ
インバウンドの仕組み
大まかな流れは以下の通りです:
- 送信者は、以下の宛先にメールを送信します。
support@reply.yourdomain.com. - DNSは、そのメールをVonageの受信SMTPサービスへ転送します。
- Vonageは、Verifyされたドメインまたはサブドメインを特定します。
- Vonageは、そのドメインに関連付けられているアプリケーションIDを検索します。
- Vonageは
POSTアプリケーションの受信用URLへのWebhookイベント。
以下の例は、代表的な Webhook ペイロードを示しています。次のようなフィールドは、 cc, recipients, contextそして reply_to 該当する場合は、メールに含められます。
ファンアウト(複数の受信先/複数のドメイン)
Vonageは、受信確認済みのドメインを持つ受信者ごとに、受信メールを1回ずつ分散させます。各分散処理について:
- このイベントには別の
message_uuidおよび別のCDR。 - イベントは、その受信者のドメインに関連付けられたアプリケーションに転送されます。
- について
recipientsこの配列には、元の受信者がすべて含まれており、文脈が完全に保持されています。 - CCアドレスは、すべての分割イベントにおいて保持されます。
- 内のVonage以外のアドレス
toまたはccフィールドはそのまま残りますrecipientsただし、追加のイベントは生成されません。
シナリオA:新規受信メール(送信に関するコンテキストなし)
送信済みメールへの返信ではない新しい受信メールについては、Vonageは以下の項目を確認します。 to 検証済みのドメインと照合し、関連付けられているアプリケーションを特定した上で、そのインバウンドURLにイベントを送信します。
{
"channel": "email",
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "support@reply.xyz.com",
"from": "abc@example1.com",
"timestamp": "2025-02-03T12:14:25Z",
"message_type": "text",
"text": "Inbound message text.",
"email": {
"subject": "Email subject",
"to_name": "support",
"cc": [
{
"address": "audit@xyz.com",
"name": "audit"
}
]
}
}
について cc このフィールドは省略可能です。これは、住所と(利用可能な場合は)名前を含む受信者オブジェクトの配列です。
シナリオ B:複数の受信者および複数のVerify済みドメイン宛ての新規受信メール(ファンアウト)
例えば、次のように仮定すると、 support@reply.xyz.com アプリケーションAに関連付けられており、 test@test.xyz.com アプリケーションBと関連付けられています。検証済みのドメインの両方に宛てられ、外部アドレスにCCが設定されたメールは、同じ受信者配列を生成しますが、異なるイベントとして記録されます。
アプリケーションAに送信されたWebhookイベント:
{
"channel": "email",
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "support@reply.xyz.com",
"from": "abc@example1.com",
"timestamp": "2025-02-03T12:14:25Z",
"message_type": "text",
"text": "Inbound message text.",
"email": {
"subject": "Email subject",
"to_name": "support",
"recipients": [
{
"address": "support@reply.xyz.com",
"name": "support"
},
{
"address": "test@test.xyz.com",
"name": "test"
},
{
"address": "external@example.net",
"name": "external"
},
{
"address": "audit@example.net",
"name": "audit"
}
],
"cc": [
{
"address": "audit@example.net",
"name": "audit"
}
]
}
}
アプリケーションBに送信されたWebhookイベント:
{
"channel": "email",
"message_uuid": "bbbbbbbb-cccc-4ddd-8eee-1234567890bc",
"to": "test@test.xyz.com",
"from": "abc@example1.com",
"timestamp": "2025-02-03T12:14:25Z",
"message_type": "text",
"text": "Inbound message text.",
"email": {
"subject": "Email subject",
"to_name": "test",
"recipients": [
{
"address": "support@reply.xyz.com",
"name": "support"
},
{
"address": "test@test.xyz.com",
"name": "test"
},
{
"address": "external@example.net",
"name": "external"
},
{
"address": "audit@example.net",
"name": "audit"
}
],
"cc": [
{
"address": "audit@example.net",
"name": "audit"
}
]
}
}
シナリオ C:送信メールへの返信(reply_to ヘッダーが設定されている場合)
受信メールに reply_to 送信側の会話を識別するヘッダーとして、このイベントには元の送信メッセージが context.
{
"channel": "email",
"message_uuid": "cccccccc-dddd-4eee-8fff-2345678901cd",
"to": "support@reply.xyz.com",
"from": "abc@example1.com",
"timestamp": "2025-02-03T12:14:25Z",
"message_type": "text",
"text": "Thanks, I have a question about my order.",
"context": {
"message_uuid": "11111111-2222-4333-8444-555555555555",
"message_from": "orders@example.com"
},
"email": {
"subject": "Re: Order confirmation",
"to_name": "support",
"reply_to": "orders@example.com",
"recipients": [
{
"address": "support@reply.xyz.com",
"name": "support"
}
]
}
}
シナリオ D:送信メールへの返信(reply_to ヘッダーが設定されていない場合)
返信に reply_to ヘッダーに、VonageはVerifyされたドメインのアドレスを挿入します。 to そして、元の送信メールを以下を通じて引き続きリンクしています context.
{
"channel": "email",
"message_uuid": "dddddddd-eeee-4fff-8000-3456789012de",
"to": "support@reply.xyz.com",
"from": "abc@example1.com",
"timestamp": "2025-02-03T12:14:25Z",
"message_type": "text",
"text": "I am following up on this request.",
"context": {
"message_uuid": "66666666-7777-4888-8999-000000000000",
"message_from": "orders@example.com"
},
"email": {
"subject": "Re: Order confirmation",
"to_name": "support"
}
}
シナリオ E:添付ファイル付きの HTML メール
HTMLメールや添付ファイルを含むメールの場合、このイベントでは message_type: "content".その content 配列には以下を含めることができます text, htmlそして file エントリ。ファイルエントリには、Vonageがホストする url および元のファイル name.
{
"channel": "email",
"message_uuid": "eeeeeeee-ffff-4000-8111-4567890123ef",
"to": "support@reply.xyz.com",
"from": "abc@example1.com",
"timestamp": "2025-02-03T12:14:25Z",
"message_type": "content",
"content": [
{
"type": "text",
"text": "Plain-text version of the message."
},
{
"type": "html",
"html": "<p>HTML version of the message.</p>"
},
{
"type": "file",
"url": "https://api.vonage.com/media/inbound/attachment-123",
"name": "order-details.pdf"
}
],
"email": {
"subject": "Order details",
"to_name": "support"
}
}
顧客ユーザーは、最大5 MBまでの添付ファイルを送信できます。Vonageは各添付ファイルをアップロードし、2日間有効なURLを提供します。
重要な動作とエッジケース
Webhookのルーティング優先度
Vonage は、以下の優先順位に従って着信イベントをルーティングします:
| 構成 | 目的地 |
|---|---|
| Applicationsに関連付けられたドメイン | アプリケーションのインバウンドURL。これは、アカウントレベルのWebhookよりも優先されます。 |
| Applicationsに関連付けられていないドメイン | 設定されている場合、AccountレベルのインバウンドWebhook。 |
| どちらも設定されていない | インバウンドイベントは破棄されます。 |
サイズの制限
ペイロードの制限と添付ファイルのサイズ制限は別々の制限です:
| 上限 | 最大 |
|---|---|
| メール本文 | 100 KB |
| ネットワークレベルでのペイロードの合計 | 200 KB |
| 個別の添付 | 5 MB |
100 KBという本文の制限は、メールの本文に適用されます。200 KBという制限は、ネットワークレベルでのペイロードの合計に適用されるものであり、添付ファイルの制限ではありません。Vonageでは添付ファイルを別途ホストし、2日間有効なURLを提供しているため、添付ファイルは最大5 MBまで可能です。