Docs: add comprehensive Mail Platform guide (BYOK, batch, logs, audiences/contacts, broadcasts, webhooks)

[Copilot]

This PR adds a developer-first Mail Platform documentation set for the Mail feature expansion introduced in #172, covering end-to-end workflows from setup and sending to delivery observability and webhook reconciliation. It also makes the new guide discoverable from Mintlify navigation and links it from the existing mail send API reference.

• New guide: guides/mail-platform

  • Added a full Mail Platform reference under mintlify/docs/guides/mail-platform.mdx.
  • Covers: architecture (queue → Resend → webhook → MailLog), plan/BYOK gating matrix, setup prerequisites, BYOK configuration, required env vars, webhook registration, endpoint-by-endpoint API behavior, dashboard UX map, security notes, error reference, and migration/changelog notes.
  • Includes implementation/security references to PRs Feat: expand Mail API ecosystem with BYOK, Broadcasts, and robust security fixes #172 and 📝 CodeRabbit Chat: Implement requested code changes #175.

• API surface documentation expansion

  • Documented both transactional and platform endpoints:
    • /api/mail/send, /api/mail/send-batch
    • /api/mail/logs, /api/mail/logs/:resendId
    • /api/mail/audiences*, /api/mail/audiences/:audienceId/contacts*
    • /api/mail/broadcasts*
    • /api/mail/webhook
  • Added curl + JavaScript SDK examples for each endpoint group and clarified response envelope/error behavior.

• Docs IA / discoverability updates

  • Added guides/mail-platform to Mintlify navigation in mintlify/docs/docs.json (Guides section).
  • Added a forward-link callout in mintlify/docs/api-reference/mail/send.mdx to route users from single-send docs to the full platform guide.

<Info>
  For the complete Mail Platform documentation (BYOK, batch sending, logs, audiences,
  contacts, broadcasts, webhooks, and dashboard workflows), see
  <a href="/guides/mail-platform">Mail Platform guide</a>.
</Info>

[yash-pouranik]

@copilot
Why there are 0 changes?

[Copilot]

@copilot
Why there are 0 changes?

There are changes in this branch at commit 73af4b4 (3 files):

• mintlify/docs/guides/mail-platform.mdx
• mintlify/docs/docs.json
• mintlify/docs/api-reference/mail/send.mdx

I also verified the diff from base (023ffcc..HEAD) shows these files. If GitHub is showing 0 in your view, it’s likely a stale/cached compare view on the PR page.

[yash-pouranik]

@coderabbitai
ok to merge?

[Copilot]

Pull request overview

Adds a new Mintlify “Mail Platform” guide and wires it into documentation navigation and the existing mail send API reference, aiming to provide end-to-end documentation for the expanded Mail feature set introduced in #172/#175.

Changes:

• Added a comprehensive guides/mail-platform MDX guide covering setup, sending, logs, audiences/contacts, broadcasts, and webhooks.
• Updated Mintlify navigation to include the new guide under “Guides”.
• Added an Info callout in the mail send API reference linking to the full platform guide.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
mintlify/docs/guides/mail-platform.mdx	New comprehensive Mail Platform guide and examples.
mintlify/docs/docs.json	Adds guides/mail-platform to the Guides navigation group.
mintlify/docs/api-reference/mail/send.mdx	Adds a callout linking readers to the full Mail Platform guide.

Comments suppressed due to low confidence (1)

mintlify/docs/guides/mail-platform.mdx:494

• This event mapping table includes email.failed → failed, but the current webhook handler does not set a status for email.failed (and it does set email.sent → sent). Please adjust the mapping to reflect the implemented statuses, or update the handler to cover email.failed if you want failed to be persisted from webhooks.

### Event mapping to `MailLog.status`

| Resend event type | MailLog status |
|---|---|
| `email.delivered` | `delivered` |
| `email.bounced` | `bounced` |
| `email.complained` | `complained` |
| `email.failed` | `failed` |
| `email.delivery_delayed` | `queued` |

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Get PR details and status
gh pr view 178 --repo geturbackend/urBackend --json title,state,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,comments,reviews,additions,deletions,changedFiles,isDraft 2>&1

echo "---CHECKS---"
gh pr checks 178 --repo geturbackend/urBackend 2>&1

echo "---REVIEWS---"
gh pr review list 178 --repo geturbackend/urBackend 2>&1

Length of output: 7649

---

@yash-pouranik Here's the current status of PR #178:

✅ Ready to merge from a technical standpoint:

• All CI checks pass (frontend-lint, dashboard-api-tests, public-api-tests, sdk-tests, python-sdk-tests, CodeQL, Analyze)
• Branch is mergeable with a CLEAN merge state (no conflicts)
• No blocking reviews

⚠️ One minor doc-accuracy note (low risk, docs-only PR):
Copilot's review flagged that the webhook event mapping table in mintlify/docs/guides/mail-platform.mdx documents email.failed → failed, but the actual webhook handler may not persist a failed status for that event. Since this is a docs PR, the risk is low, but you may want to verify this mapping against the handler in #172/#175 before merging to keep the docs accurate.

If you're comfortable with that, the PR looks good to go. Would you like me to approve it?

[yash-pouranik]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Done — I applied the review-thread changes in 7b3f0ba and follow-up clarifications in 7f36899.

[yash-pouranik]

@coderabbitai
please check if the issues are solved?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

Let me check the review thread and the current state of the files.

---

🏁 Script executed:

#!/bin/bash
# Get the specific review and its comments
gh api repos/geturbackend/urBackend/pulls/178/reviews 2>&1

echo "---REVIEW COMMENTS---"
gh api repos/geturbackend/urBackend/pulls/178/comments 2>&1

echo "---CURRENT FILE STATE---"
cat mintlify/docs/guides/mail-platform.mdx 2>&1 || echo "File not found at that path"

echo "---FILE SEARCH---"
fd "mail-platform" 2>&1

Length of output: 90964

---

@yash-pouranik Yes, all 5 issues from the Copilot review have been addressed in the current file. Here's a summary:

#	Issue	Status
1	/api/mail/send-batch incorrectly described as queue-backed	✅ Fixed — overview and architecture diagram now correctly distinguish single-send (BullMQ) from batch-send (direct Resend call)
2	Dashboard path inconsistency (/:projectId/... vs /api/projects/:projectId/...)	✅ Fixed — heading and live-status bullet now use the full /api/projects/:projectId/mail/logs path
3	Webhook secret fail-closed claimed HTTP 500, but real behavior is HTTP 200	✅ Fixed — section now documents the actual 200 + "Webhook ignored: secret not configured." behavior
4	email.failed documented but not handled; email.sent handled but not documented	✅ Fixed — event mapping table now shows email.sent → sent and drops email.failed; "Register webhook" events list updated to match
5	Response envelope stated "All responses follow …" but webhook 400 omits data	✅ Fixed — changed to "Most endpoints follow …" and added an explicit webhook 400 response block without data

The PR looks good to merge from a docs-accuracy standpoint. Would you like me to approve it?

[yash-pouranik]

but comments are not resolved yet??

@coderabbitai

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

Let me check which review threads are still open on the PR.

---

🏁 Script executed:

#!/bin/bash
# Get all review comments and their resolution status
gh api repos/geturbackend/urBackend/pulls/178/reviews --jq '.[] | {id: .id, user: .user.login, state: .state, body: .body[:100]}' 2>&1

echo "---REVIEW THREADS (pull request review comments)---"
gh api repos/geturbackend/urBackend/pulls/comments \
  --jq '.[] | {id: .id, user: .user.login, resolved: .pull_request_review_id, body: .body[:120], path: .path}' 2>&1

echo "---UNRESOLVED THREADS via GraphQL---"
gh api graphql -f query='
{
  repository(owner: "geturbackend", name: "urBackend") {
    pullRequest(number: 178) {
      reviewThreads(first: 30) {
        nodes {
          id
          isResolved
          isOutdated
          comments(first: 5) {
            nodes {
              author { login }
              body
              path
              line
            }
          }
        }
      }
    }
  }
}' 2>&1

Length of output: 11334

---

@yash-pouranik You're right — 3 of the Copilot review threads are still open (not resolved on GitHub). Here's the breakdown:

Thread	Issue	Status
Line 43 — send-batch queue description	Docs describe /api/mail/send-batch as queue-backed, but it calls Resend directly	🔴 Unresolved (not outdated)
Line 97 — webhook event mapping	email.failed documented but not handled; email.sent handled but not documented	🔴 Unresolved (not outdated)
Response envelope — "All responses follow..."	Webhook 400 omits data field, contradicting the stated envelope shape	🟡 Unresolved (but outdated)

Important: These are Copilot's review threads, not mine — I can only resolve my own (CodeRabbit) comments programmatically. You'll need to manually resolve these three threads on GitHub by clicking "Resolve conversation" on each one, once you're satisfied the fixes were applied correctly.

The code changes Copilot SWE agent made (commits 7f36899 / 7b3f0ba) appear to address thread 1, which is why that one looks fixed in the file content. Threads 4 and 5 may need a closer look at the current file to confirm the fixes landed. Would you like me to re-read the current mail-platform.mdx to verify?

[yash-pouranik]

yes please
@coderabbitai

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

Sure! Let me re-read the current state of mail-platform.mdx to verify the fixes.

---

🏁 Script executed:

#!/bin/bash
# Read the current file to check the three flagged sections
cat mintlify/docs/guides/mail-platform.mdx

Length of output: 17472

---

@yash-pouranik All three open Copilot review threads are now fully addressed in the current file. Here's the verification:

#	Thread	What was required	Current state
1	Line 43 — send-batch queue description	Distinguish single-send (BullMQ) from batch-send (direct Resend call)	✅ Fixed — Overview says "direct provider batch sending (/api/mail/send-batch)", architecture diagram clearly labels BullMQ mail queue (single-send path) vs Resend API (batch-send direct path)
2	Line 97 — webhook event mapping	Add email.sent → sent, remove undocumented email.failed	✅ Fixed — event table now has email.sent → sent and email.failed is absent from both the table and the "Register webhook" events list
3	Response envelope	"All responses follow…" was wrong since webhook 400 omits data	✅ Fixed — now reads "Most endpoints follow…" and the webhook 400 block is shown separately without a data field

The docs are accurate. The only remaining step is to manually click "Resolve conversation" on those three Copilot threads in GitHub, since I can only programmatically resolve my own CodeRabbit comments. Once you do that, the PR is ready to merge. Would you like me to approve it?