docs: add cold email outreach use-case guide and consolidate nav - #41
Conversation
Adds a "Use cases" nav group with its first page: a cold outreach and GTM setup guide covering bring-your-own sending accounts, the sending key, and connecting an AI client over MCP. The page links out to the existing guides rather than restating them. What it adds that no current page covers: - A direct answer to "do you need a domain for cold email?" (no, not when you send through your own accounts), placed before the steps because it is the biggest perceived blocker. - The MCP authorisation detail that every product line is preselected, so a sending-only setup means clearing Management and Mailbox. A Sending-only grant never asks you to choose a mailbox. - That any provider giving you SMTP credentials works as a Custom SMTP account. Named as plain text, framed as "works as", not as a supported integration, since there is no vendor-specific connector. GTM is carried in the title, description, keywords, a dedicated H2 and the intro, but not in the slug: in a docs context "gtm" competes with Google Tag Manager, and the head term with proven volume is "cold email outreach". Also corrects guides/sending-via-http.mdx, which listed a verified custom domain as an unconditional prerequisite. That is only true for the managed account. Customers on their own providers can send from any domain without registering it, per the contract in provider-selection.js: sender-domain filtering excludes managed SES providers only. Left as-is, the two pages would have contradicted each other, and both feed the generated llms-full.txt. Nav consolidation: Billing (one page) folds into Teams and access, CLI (one page) folds into SDKs, renamed "SDKs and CLI". Eleven groups become ten. Group membership does not affect page URLs in Mintlify, so no redirects are needed. Screenshots are still to come; the page currently reuses the two existing sending-account images and ships og:title and og:description without og:image, since a dangling og:image renders worse than Mintlify's generated default. Verified: confidentiality:check, external-links:check, mint validate, mint broken-links. Copy greps clean for em-dashes, banned vocab, US spellings and placeholder demo data.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 513c3c0824
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| </Step> | ||
|
|
||
| <Step title="Send from your tool or your agent"> | ||
| Three routes, same key: |
There was a problem hiding this comment.
For users choosing the MCP path, hosted MCP does not use the smx_mbx_ key created in the preceding step; it authorizes a connected app and issues separate short-lived OAuth tokens. guides/api-keys.mdx explicitly distinguishes connected apps from manual keys and states that connected apps do not create smx_mbx_ secrets. Calling these “Three routes, same key” therefore instructs MCP-only users to create and store an unnecessary credential and misrepresents how its sending scope is authorized. Make key creation conditional on SMTP/HTTP and describe hosted MCP as a separate OAuth route.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 636b746. Correct, and it was a real factual error rather than a wording nit: guides/api-keys.mdx is explicit that connected apps never create smx_mbx_ secrets, so "three routes, same key" told MCP-only readers to create and store a credential they will never use, and described their sending access as authorised by something it is not.
Restructured into three steps: pick the route and see which credential it needs (small table), create a sending key scoped to SMTP and HTTP with an explicit skip note for MCP-only users, then MCP as its own step stating plainly that it uses no key and linking to Connected apps. The pre-campaign checklist item is conditional now too.
… routes The setup steps created a sending key and then listed MCP alongside SMTP and HTTP as "three routes, same key". Hosted MCP does not use that key: it authorises a connected app and issues its own short-lived tokens, and guides/api-keys.mdx is explicit that connected apps never create smx_mbx_ secrets. An MCP-only reader was being told to create and store a credential they will never use, with the wrong account of how their sending access is authorised. Splits the flow: a short step to pick the route and see which credential it needs, then key creation scoped to SMTP and HTTP with an explicit skip note, then MCP as its own step that says plainly it uses no key. The pre-campaign checklist item is now conditional too.
…the title Four screenshots, all supplied from the live app: - The MCP authorisation screen with Sending API the only product line ticked. This is the one the prose could not carry on its own. - Create API Key with Sending Key selected. - The Accounts table showing a pool of inboxes with their delivery groups and per-minute, per-hour and per-day caps. - One account's Advanced settings with sender identity, quotas, distribution percentage and delivery group in a single frame. Two of the four arrived as CleanShot selection captures with largely transparent backgrounds (alpha means of 37 and 108 out of 255). Left alone those would have shown the Mintlify page background through the UI, which in dark mode means dark text on dark. All four are flattened onto white to match the light-themed control panel, then palette-quantised: 406K to 126K, 225K to 80K, 182K to 57K, 85K to 29K, with no visible loss on text. The screenshots also corrected the copy. The authorisation screen labels its options "Mailbox API", "Management API" and "Sending API" under a "Product lines" heading, not the bare surface names the page had been using, so every reference now matches what the reader actually sees. Title shortened to "Cold email outreach and GTM from your own inboxes": 49 characters, 59 once Mintlify appends the brand suffix, so it stays inside the 60-character limit while keeping both target terms and front-loading the head one. og:title synced. The domain-requirement table now reads "Send through the managed SES from Sendmux" rather than "the managed account". Also carries an unrelated root font-size tweak in style.css, 105% to 103%, made by the repo owner and kept deliberately. Verified: confidentiality:check, external-links:check, mint validate, mint broken-links, and copy greps for em-dashes, banned vocab, US spellings and placeholder demo data.
1 participant
Adds a Use cases nav group with its first page: a cold outreach and GTM setup guide covering bring-your-own sending accounts, the sending key, and connecting an AI client over MCP.
What the page adds
It links out to the existing guides rather than restating them. Three things it covers that no current page does:
GTM sits in the title, description, keywords, a dedicated H2 and the intro, but not in the slug: in a docs context "gtm" competes with Google Tag Manager, and the head term with proven volume is "cold email outreach". Keyword research is recorded in the SITE repo's
seo/keywords.md.A correction, worth reviewing on its own
guides/sending-via-http.mdxlisted a verified custom domain as an unconditional prerequisite. That is only true for the managed account.Verified against
smtp-proxy/app/consumer/lib/provider-selection.js:103-150, which carries an explicit contract: customers on their own SMTP/API providers can send from any domain without registering it, andfilterProvidersForSenderDomain()excludes managed SES providers only. Corroborated byapp/tests/unit/provider-selection-shared-domain.test.js:293-329and an anti-revert block inauth_mysql_redis.js:559-588recording three regressions where someone added an SMTP-time domain check and broke exactly these customers.Left as-is, the two pages would have contradicted each other, and both feed the generated
llms-full.txt.Nav consolidation
Billing (one page) folds into Teams and access. CLI (one page) folds into SDKs, renamed SDKs and CLI. Eleven groups become ten.
No redirects needed: in Mintlify a page URL derives from its file path, not its nav group.
guides/billing.mdxalready sits in a group called "Billing" and resolves at/guides/billing. No.mdxfile moves here.Still to come
Screenshots. The page currently reuses the two existing sending-account images and ships
og:title+og:descriptionwithoutog:image, since a danglingog:imagerenders worse than Mintlify's generated default. Five control-panel captures are outstanding, the most valuable being the MCP consent screen with Management and Mailbox cleared.Verified
confidentiality:check,external-links:check,mint validate,mint broken-links. Copy greps clean for em-dashes, banned vocab, US spellings and placeholder demo data.https://claude.ai/code/session_01EGuSNjJhi97uNH8EHq7QAt