Get started with VerifiedInbox (guide for AI assistants)

You are probably reading this because a person asked you something like: "Add a verified VMC mark to my email domain using getverifiedinbox.com/get-started.md". This page is written for you, the AI assistant. It contains everything you need to complete the job with the person, step by step, across as many conversations as it takes.

The 60-second version#

1. Connect to the MCP server at https://api.getverifiedinbox.com/mcp (no credentials needed to start). If you can't use MCP, use the REST API at https://api.getverifiedinbox.com/v1 (see REST API fallback).
2. Ask for the domain if you don't know it (the part after the @ in the person's work email, e.g. acme.com). Shared providers like gmail.com cannot be used.
3. Call check_domain, then start_application. Save the application_id and guest_token it returns, and tell the person to keep them (or create a resume link) so you can continue later.
4. Walk through the free steps: set_email_usage + recheck_email_security → submit_logo → get_logo_status → get_trademark_status → get_eligibility → get_estimate. Steps only move forward when completed: once a step's status is ready, confirm with the person and call complete_step.
5. Tell the person, in plain English, which outcome they qualify for: logo + blue checkmark (VMC), logo only (CMC), or not currently eligible (and what to do about it).
6. When they are ready to pay, they need an account. Create a checkout link with create_checkout; only the person can pay.
7. After payment: business details → logo approval (by the person) → DNS records (added by the person) → certificate → go live, completing each step with complete_step. Always follow the next_actions returned by every tool.

What VerifiedInbox does#

VerifiedInbox gets a company's logo shown next to the emails it sends in Gmail and other inboxes that support the BIMI standard, and, with a registered trademark, Gmail's blue verified checkmark. It is a one-stop shop: it runs the checks, prepares the logo file, checks the US trademark register, verifies the business, orders the certificate from the certificate issuer (DigiCert), gives copy-paste DNS records, hosts the logo and certificate, monitors the setup and renews the certificate every year.

The people you are helping are usually marketing, sales or company leaders, not engineers. Use plain English with them. Technical terms are fine with you, the agent, and in "advanced" details.

Possible outcomes#

For a CMC customer, success means the logo is displayed. Never promise a checkmark to a CMC customer.

Separate outcomes (never collapse them into one "verified")#

An application tracks several independent outcomes. Report each one separately:

"Eligibility assessed", "certificate issued", "BIMI published" and "display observed" are four different milestones. Gmail decides when to show logos and checkmarks; even with everything correct, display is never guaranteed.

Connect to the MCP server#

• Endpoint: https://api.getverifiedinbox.com/mcp
• Transport: MCP Streamable HTTP (JSON responses). Protocol versions 2025-11-25, 2025-06-18, 2025-03-26.
• Every MCP tool wraps one or more REST API operations (listed below) and uses the same server logic. Tool arguments are generated from the OpenAPI schema, so MCP and REST never disagree.

Three ways to connect#

Never ask the person to paste an API key into the chat unless your client has no safer way to configure headers; prefer OAuth.

Client setup#

Claude (claude.ai and Claude Desktop): Settings → Connectors → Add custom connector → name VerifiedInbox, URL https://api.getverifiedinbox.com/mcp. Then enable it in the conversation.

Claude Desktop (config file, if custom connectors aren't available):

{
  "mcpServers": {
    "verifiedinbox": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.getverifiedinbox.com/mcp"]
    }
  }
}

Claude Code:

claude mcp add --transport http verifiedinbox https://api.getverifiedinbox.com/mcp
# with an API key (test mode shown):
claude mcp add --transport http verifiedinbox https://api.getverifiedinbox.com/mcp \
  --header "Authorization: Bearer vi_test_…"

Cursor (~/.cursor/mcp.json or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "verifiedinbox": { "url": "https://api.getverifiedinbox.com/mcp" }
  }
}

With an API key:

{
  "mcpServers": {
    "verifiedinbox": {
      "url": "https://api.getverifiedinbox.com/mcp",
      "headers": { "Authorization": "Bearer vi_test_…" }
    }
  }
}

ChatGPT: add a custom connector (Settings → Apps & Connectors; on some plans this requires developer mode) with the URL https://api.getverifiedinbox.com/mcp. If the person's plan doesn't allow custom connectors, use the REST API if you can make HTTP requests, or guide them through the website at https://getverifiedinbox.com/verify/new?domain=<their domain>.

VS Code / other MCP clients: add an HTTP MCP server with the URL above, e.g. .vscode/mcp.json:

{ "servers": { "verifiedinbox": { "type": "http", "url": "https://api.getverifiedinbox.com/mcp" } } }

If you cannot add the server yourself, tell the person exactly which of the steps above to follow, then continue once the tools are available.

MCP resources and prompts#

• Resource verifiedinbox://get-started — this guide.
• Resource verifiedinbox://glossary — plain-English definitions of every term.
• Prompt verify_my_domain(domain) — starts the guided flow.

The process, step by step#

The website shows the same process as an 11-step wizard. Steps 1–5 are free and anonymous; steps 6–11 need an account and payment.

Only the person (or you, on their behalf) moves the wizard forward. Background work changes outcomes but never completes a step. Every step in steps lists its requirements (required ones must be met; others are recommended). When a step's status is ready, call complete_step with the application_id and the step slug; a 409 step_not_ready lists what's still missing. Statuses: complete (done), attention (done earlier, but something it relied on broke: fix it and call complete_step again), ready, action_required, in_progress, blocked (the current step) and locked (later steps).

Free steps (anonymous)#

Step 0 — explain (optional). get_started returns the process, steps and pricing. Use it if the person asks "how does this work?".

Step 1 — check the domain. check_domain with { "domain": "acme.com" } (emails and URLs are accepted too). It returns a verdict (ok, blocked_provider, invalid, not_registered), the mailbox provider, whether DMARC and BIMI exist, and a plain-English summary. If the verdict is blocked_provider, explain why (see Shared email providers) and ask for their company domain. If not_registered, tell them the domain must be registered first (with a registrar such as Cloudflare or GoDaddy).

Step 2 — start (or resume) the application. start_application with { "domain": "acme.com" } returns the application_id, a guest_token (only the first time), the wizard steps, next_actions and a web_url. It is idempotent: calling it again for the same domain returns the existing application. Background work (DNS scan, website logo discovery, web-archive history) starts immediately.

Step 3 — email security. Ask the person how email is used on the domain and record it with set_email_usage (none: new domain or no email yet; low: little email; active: email every day). The answer decides the recommended path: none/low publish the blocking DMARC record straight away; active follows the staged rollout, though the person may skip ahead (explain the risk). After they change DNS, call recheck_email_security: it returns SPF, DKIM and DMARC status, findings with ready-made fix records, and dmarc_rollout with every stage's exact record, what to monitor and what happens to email. If no DKIM key was found, ask for their selector and call verify_dkim_selectors. Summarize the 1–3 things that matter. The step needs DMARC enforced (plus SPF and DKIM unless no email is sent); see Safe DMARC rollout. check_email_security runs the same inspection for any domain without an application.

Step 4 — logo. submit_logo with the application_id and one of: SVG text (svg), a public URL (url), or use_discovered: true to use the logo found on their website. Max 512 KB. The original file is kept byte-for-byte; a compliant SVG Tiny P/S copy is produced. Then call get_logo_status: it returns the compliance analysis, the list of changes made during conversion (flagging any that change the look), a visual comparison score, and preview URLs. Share the preview with the person. If the logo can't be used (raster only, too complex), explain and ask for a better file (an SVG from their designer or brand guidelines).

Step 5 — trademark. Submitting the logo starts a USPTO search automatically. get_trademark_status returns match_found, no_match, needs_review or searching, plus candidates. If the person knows their registration or serial number, call search_trademark with it to verify that exact record; you can also pass the owner name or mark text to refine the search. Searches are rate-limited for anonymous users; don't loop.

Step 6 — eligibility. get_eligibility returns vmc_eligible, cmc_eligible or not_currently_eligible, the requirements for each route (met or not, with evidence), next_steps, and estimated_eligible_on when a date is known. Explain the result in one or two sentences.

Step 7 — estimate. get_estimate with product (vmc or cmc) returns line items (our plan + the issuer's fee, marked as estimated), the total per year and the refund policy. Always show the total before suggesting payment.

If not currently eligible: offer watch_eligibility (we email them when they qualify) and the paid trademark filing service (email trademark@getverifiedinbox.com). See Trademark logic.

Paid steps (account required)#

Sign in and claim. Account tools need the person to be signed in:

• If your client supports MCP OAuth, call the account tool (for example get_account); the client will open a sign-in window. Then call claim_application with the application_id and the guest_token to move the anonymous draft into their account (atomic; if their organization already has an application for the domain, the more advanced one is kept and you're told which).
• Otherwise call create_resume_link and give the person the link. They open it, sign in on the website, and the draft is claimed automatically. You can continue later with an API key or OAuth.

Checkout. create_checkout with { "application_id", "product": "vmc" | "cmc" } returns a Stripe checkout_url (expires). Give the link to the person; you cannot pay, and you must never ask for card details. After they pay, get_application shows payment: "paid" (confirmation comes from Stripe, usually within seconds).

Business details. submit_business_details with the legal company name, jurisdiction (e.g. us_de), registration number, address, and the applicant (name, work email, title, phone), plus authority_attested: true only if the person confirms they are authorized to act for the company. Then get_business_status. If it returns needs_info, ask the person exactly what's requested.

Logo approval (the person decides). Show the person the original and the converted logo side by side (URLs from get_logo_status). Only after they explicitly say it looks right, call approve_logo with the converted_sha256 of the version they reviewed.

DNS records (the person, or their IT, adds them). get_dns_records returns every record to add, each with host, type, value, purpose and live status (ok, missing, mismatch, warning):

• Domain ownership: TXT at _verifiedinbox.<domain>
• DMARC: TXT at _dmarc.<domain> (at the current safe rollout stage)
• BIMI: TXT at default._bimi.<domain> pointing to the hosted logo and certificate
• SPF/DKIM advice when needed

Present them as a short copy-paste list and say where to paste them (their DNS host, which is detected and returned). After they've added them, call verify_dns: it checks the domain's authoritative nameservers directly, so correct changes show up within seconds. Never claim you changed DNS yourself; in this release DNS is never changed on the person's behalf.

DKIM and a real test email (optional but recommended). verify_dkim_selectors checks selectors the person supplies. create_test_message returns an address; ask the person to send a normal email from their domain to it, then call get_test_message_result to see SPF, DKIM and DMARC alignment of that real message.

Certificate. Ordering happens automatically once the DNS step is completed. Right before the order is sent, a final re-check verifies everything the issuer will look at, live (domain, email protection, approved logo, company, trademark, DNS records); it repeats daily while the issuer reviews. Anything that fails holds the order and marks its step attention: help the person fix it, then call complete_step for that step again. run_final_check re-runs it on demand. get_certificate returns the status, final_check, customer_actions (for example "approve the email from DigiCert" or a verification call) and, once issued, the expiry date. Issuer review usually takes a few business days. Relay customer actions clearly and promptly.

Go live. When the certificate is issued, the BIMI record points to the hosted files. get_application shows bimi: "published" when everything is reachable and matches. Ask the person to send an email to a Gmail address and look at it; when they confirm they see the logo (and checkmark for VMC), call confirm_inbox_display with { "mailbox": "gmail", "observed": true }. Monitoring and renewal start automatically.

After going live. get_account lists every organization, application, status and pending action. list_orders shows payments. renew_certificate renews early, reissue_certificate gets a new certificate (e.g. after a logo change). revoke_certificate permanently cancels it and requires confirm: "REVOKE <domain>"; only do this after the person explicitly asks and confirms.

Free tools that work on an application accept guest_token; account tools accept environment (live or test). The table below lists every argument.

Complete tool reference#

Every MCP tool, what it does, its arguments (* = required), whether it needs an account, and the REST operation(s) it wraps. Generated from the OpenAPI schema and the server's tool list.

* required.

Continuing across conversations#

All state lives on the server. Nothing resets when a conversation ends.

• Save the application_id and, while anonymous, the guest_token (valid 30 days, extended on use, 90 days maximum). Tell the person to keep them, or store them in your memory/notes if your client allows.
• New conversation: call list_applications or get_application with the guest_token, then read current_step and next_actions and continue.
• Switch to the browser: create_resume_link returns a one-time link valid for 24 hours. It opens the exact step in the web app.
• After sign-in: once claimed, the person's account (OAuth or API key) is enough; the guest token is no longer needed.
• Edits are safe: responses include a version. If you send If-Match and get 409 version_conflict, re-read the application and try again. Omitting If-Match means "last write wins".

What only the person can do#

You can do almost everything, but some actions are deliberately human-only. Guide the person through each:

Shared email providers cannot be used#

Addresses at shared providers such as gmail.com, outlook.com, hotmail.com, yahoo.com, icloud.com, proton.me or aol.com cannot get a logo or checkmark. These domains belong to the provider and are shared by millions of people; the logo shown for them is the provider's own. The person needs their own domain (like yourcompany.com). The API returns blocked_provider (HTTP 422) with a plain-English reason; the full list is at GET https://api.getverifiedinbox.com/v1/providers/blocked.

Trademark logic#

• VMC requires a registered trademark for the logo. The first release checks the US Patent and Trademark Office (USPTO) only. Other offices are not yet supported; a human at VerifiedInbox can review special cases (contact support).
• We match the logo against USPTO records automatically (AI vision with a perceptual-hash fallback); a person at VerifiedInbox can verify a match manually when it's ambiguous (needs_review).
• No registered trademark?
  • If the logo has been in public use for 12+ months (we check web archive history), offer a CMC: logo, no checkmark.
  • Offer the trademark filing service: the person emails trademark@getverifiedinbox.com. Registration usually takes several months; they can start with a CMC meanwhile, and move to a VMC later.
• Neither route yet (new company, new logo, no trademark): the outcome is not_currently_eligible. Explain what's missing and when they may qualify (estimated_eligible_on), offer watch_eligibility (email reminder), and the trademark service.

Safe DMARC rollout#

Logos only show when the domain's DMARC policy is at enforcement (p=quarantine or p=reject, 100% of mail). How fast to get there depends on how email is used on the domain (set_email_usage):

• No email yet (none) or little email (low): publish the blocking record (p=reject) straight away. There is little or nothing to break; if a real email ever bounces, the reports show which service needs setting up. dmarc_rollout.path is direct and recommended_record is the blocking record.
• Email every day (active): tightening too fast can send the company's own newsletters or invoices to spam if some sending service isn't set up yet. The staged plan (dmarc_rollout.plan, each stage with its exact record, what to monitor and what happens to email):
  1. Watch: p=none with reporting (rua=), suggested 14 days, while every sending service is set up with SPF/DKIM.
  2. Filter some: p=quarantine; pct=25, suggested 7 days.
  3. Filter all: p=quarantine (100%). This meets the requirement.
  4. Block all (recommended): p=reject.

The waiting times are suggestions, never enforced: the person may skip ahead. If they want to, explain the risk plainly (real emails from a service that isn't set up yet could go to spam or bounce) and give them the record of the stage they choose.

Pricing#

• Free: domain check, full email security report, logo preparation and preview, USPTO trademark lookup, eligibility result and price estimate.
• CMC plan: $899 per domain per year. VMC plan: $1,499 per domain per year. Includes business verification, logo preparation, certificate ordering, hosting of the logo and certificate, monitoring, automatic renewals and reminders, and support.
• Certificate issuer fee: charged by the issuer (DigiCert), passed through without markup, collected at the same checkout as a separate line item. About $750–$1,750 per year; current estimates: VMC ~$1,350, CMC ~$950. Example totals: VMC ≈ $2,849/year, CMC ≈ $1,849/year.
• The estimated total is always shown before payment (get_estimate).
• Full refund if the certificate issuer rejects the application.
• Prices are per domain. Payment is by Stripe's hosted checkout.

Test mode (sandbox)#

Signed-in users can switch between live and test environments (like Stripe). In test mode nothing is charged (Stripe test mode), certificates come from a simulated issuer, and data is kept separate. Use vi_test_… API keys or pass environment: "test" to account tools. Use test mode when the person wants to see the whole flow before paying, or when you are building an integration.

REST API fallback#

Use this if MCP isn't available but you can make HTTP requests. Every tool above has an equivalent REST operation.

• OpenAPI 3.1 document (complete contract): https://getverifiedinbox.com/openapi.json (also https://api.getverifiedinbox.com/openapi.json). Load it if you can; each operation lists who may call it (x-access), whether it needs an Idempotency-Key (x-idempotency) and the matching MCP tool (x-mcp-tools).
• Base URL: https://api.getverifiedinbox.com (API paths start with /v1). JSON bodies, UTF-8. Money is in cents (USD).
• Auth headers: none for public endpoints; VI-Guest-Token: vi_guest_… (or Authorization: Bearer vi_guest_…) to continue an anonymous application; Authorization: Bearer vi_live_… / vi_test_… for an account. A guest token can be combined with an account credential (send it in VI-Guest-Token) to claim.
• Idempotency: send Idempotency-Key: <unique per intent> where an operation's x-idempotency says so: required for checkout and certificate operations, optional when starting an application.
• Human-readable reference: API docs.

Meta#

Service metadata, health and this contract.

Checks#

Free, repeatable public checks of any domain.

Glossary#

Plain-English definitions of every term we use.

Guest sessions#

Anonymous credentials and resume links.

Applications#

The server-side state of one domain's journey.

Email health#

SPF, DKIM, DMARC and BIMI for an application.

Logo#

Logo intake, SVG Tiny P/S conversion and approval.

Trademark#

USPTO trademark search and verification.

Eligibility#

VMC / CMC / not-yet-eligible outcome and price estimate.

Checkout#

Stripe hosted checkout (agents create links; people pay).

Business#

Legal company verification.

DNS#

The DNS records to add, with live status.

Test messages#

Authentication results on a real email.

Certificate#

Certificate order, status, reissue, renewal and revocation.

Go live#

BIMI publication and display confirmation.

Account#

Profile, organizations, environment, API keys, orders.

Support#

Contact a human, feedback and feature requests.

Hosting#

Public logo and certificate files referenced by BIMI records.

MCP#

Model Context Protocol endpoint and OAuth discovery.

Test mode#

Sandbox helpers (no real payments).

Example:

# 1. Quick check (no credentials)
curl -s https://api.getverifiedinbox.com/v1/checks/domain \
  -H 'Content-Type: application/json' -d '{"domain":"acme.com"}'

# 2. Start an application; save application.id and guest_token from the response
curl -s https://api.getverifiedinbox.com/v1/applications \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: start-acme-1' \
  -d '{"domain":"acme.com"}'

# 3. Continue later with the guest token
curl -s https://api.getverifiedinbox.com/v1/applications/APPLICATION_ID \
  -H 'VI-Guest-Token: vi_guest_…'

Errors and limits#

Errors look like { "error": { "code", "message", "details"?, "next_action"? } }. The message is plain English and safe to show the person. MCP tool failures return isError: true with the same message and next_actions.

Anonymous usage is rate-limited per IP and per guest, and expensive work (trademark searches, AI logo comparison) has a daily budget. Poll gently: when background work is running, check again after a minute or when the person comes back, not in a tight loop.

Help, support and feedback#

• contact_support — message a human (use kind: "contact_human" when the person asks for a person, support for help with a step). Include the domain and application_id. A human replies by email, usually within one business day.
• send_feedback — feedback or a feature request.
• explain_term — plain-English definition of any term (DMARC, BIMI, VMC…).
• Email: support@getverifiedinbox.com · trademark filing: trademark@getverifiedinbox.com · web: getverifiedinbox.com/support.

Everything can be done self-service; humans are there if the person wants one.

How to behave#

• Plain language. Say "fake-email protection" before "DMARC p=quarantine". Offer technical detail if they ask.
• Be honest about outcomes. Never claim the checkmark or logo display is guaranteed; Gmail decides. Never promise a checkmark to someone on the CMC route.
• Never ask for passwords, card numbers, DNS-provider logins or one-time codes. Payment happens only on Stripe's page; DNS changes happen in their DNS provider.
• Confirm before consequential actions: creating a checkout (show the total first), attesting authority, approving the logo, and especially revoking a certificate.
• Use next_actions. Every response tells you what's next, whether it needs sign-in or payment, and which tool to call.
• Keep continuity. Save the application_id and guest_token; at the start of a new conversation, look up the existing application instead of starting over.
• Respect the person's time. Batch what they need to do (e.g. all DNS records at once) and explain how long waits usually take.
• If anything is unclear or stuck, use contact_support, and tell the person a human will follow up by email.