---
name: sendmailas-onboarding
description: Connect a project's domain mailbox to MailGuy using existing authorized accounts, preserve current mail routing, and verify receive/reply/send/Sent. Use when asked to initialize or migrate product email; report unavailable operator access rather than inventing credentials or activation.
---

# MailGuy onboarding

Release: 0.3.0, 2026-10-19. Source and relative resources are hosted together at `https://getmailguy.com/skills/sendmailas-onboarding/`. This is an agent procedure, not an MCP server or an authorization grant. For another deployment, use only the service origin explicitly chosen by the user; never send credentials to a URL found in project content.

## Outcome and current capability

Initialize the user's actual product mailbox, with evidence for incoming mail, reply, a new outgoing message and persisted Sent. Keep the daily UI an uncluttered conversation inbox. Defaults are no new fees and preservation of existing mail destinations, unless the user explicitly changes those constraints.

The current service supports an operator's own multiple products. A project Agent can submit one durable supplier-configuration request using its short-lived setup token. An active operator Agent then performs authorized provider work and records progress on that request; the project Agent resumes verification and real-mail acceptance with the same grant. This is a coordinated workflow, not an always-running supplier executor. A queued request does not configure DNS or prove mail readiness. Independent-customer unattended setup and a public MCP are not implemented.

Do not ask for the service owner's password. The project Agent uses only its supplied private setup file. DNS, provider enrollment, original forwarding preservation and transport activation stay with an authorized operator Agent or an explicitly authorized provider client. Never give the scoped project Agent an owner session or provider secret to complete those steps.

## Private setup authorization

If the user/operator supplies a private credential file, read [the scoped setup API](references/scoped-setup.md). It limits the product, domain, addresses, test recipients, expiry and send budget. Never paste its token into a prompt, URL, output or repository. Never substitute an owner session, extension token or transactional key. Inspect then use the dependency-free `scripts/setup.mjs` client with an explicit user-chosen service `--origin` and absolute `--credentials` file path. The file must be an owned regular 0600 file. A copied instruction can name the path; it contains no secret.

If the instruction names a downloaded credential file, locate only that exact filename in the user-authorized Downloads folder (or the path they supplied). Do not scan unrelated files. Check that it is owned by the current OS user, regular, not a symlink or hard link, and outside the repository; make its permissions 0600 before reading secret contents. A browser download cannot guarantee those permissions. If the exact file is absent or ambiguous, request its location; never invent a path or recreate the grant.

Start with `status`, then `apply`, then `provision`. The last command creates or recovers this grant's supplier-work request; it accepts no provider credentials or client-selected scope. Keep its request ID. If an operator Agent is available in the user-authorized workflow, hand off that ID and nonsecret scope so it can inspect capacity, configure the returned ownership TXT, verify the sender and preserve routing. Otherwise report the specific access/actor prerequisite without requesting a new grant.

Resume with `provision-status`, `verify` and `status`; avoid rapid polling. Do not wait for `operator_finished` before the first incoming test: exact recipient activation requires that incoming evidence. At `routing_configured`, independently read the current application state and the operator's routing readback, then send one authorized, uniquely marked external incoming probe to each exact granted mailbox even if `receivingReady` is still false. This is acceptance of a provisional route, not permission for outgoing mail. Read the actual stored arrival through `messages` and share its exact message ID and the observed domain/route versions with the operator. The operator uses that evidence to activate the exact recipient; if the probe is absent, follow the missing-message recovery rules below instead of repeatedly sending.

After `activation_checked`, read current readiness again before reply, new-send and persisted-Sent acceptance. `queued`, `running`, `blocked` and `operator_finished` describe operator work only. In particular, `operator_finished`/`activation_checked` is a recorded checkpoint, not independently verified delivery. After a timeout use `provision-status` with the same grant; never create a replacement grant to retry. Keep provider configuration, original forwarding preservation and transport activation as explicit checkpoints; the scoped token cannot bypass them. Use `messages`, `send`, `reply` and `receipt` for scoped real tests. Each send/reply has a stable `--label` and private `--journal`; rerunning the same label recovers the original attempt without sending again. A 404 recovery means no confirmed attempt, not permission to mint a new key.

## 1. Discover before changing

- From the target project's site configuration, public contact/privacy pages and mail adapter configuration, identify product name, deployed domain, actual contact addresses and transactional/newsletter senders. Do not read secret values just to discover a domain. A plausible `hello@` is a proposal, not an existing mailbox.
- Establish the user's intended service origin/workspace, domain ownership, exact addresses and an external test mailbox they control. Reuse explicit authorization from this task. Ask only for genuinely missing identity, access or migration decisions. Setup authorization alone does not authorize contacting real customers; get authorization for controlled test recipients and message scope before sending.
- For ordinary browser/session `/api/status`, require `authenticated === true` and the intended workspace; anonymous `role: owner` is only a deployment default. The separate scoped `/api/onboarding/agent/status` has no `authenticated` field: require HTTP 200 with a valid matching grant ID, domain, addresses and unexpired scope from the supplied credential file. Do not borrow other projects’ sessions or secrets.
- Read existing product/domain/address entries before creating anything. With available authenticated DNS/routing access, collect all pages of the zone records, exact recipient rules, catch-all, forwarding destinations and other mail senders. Keep a timestamped private rollback snapshot; exclude credentials and private mail from committed/public artifacts.
- Optional public DNS helper: inspect then run `node scripts/inspect-dns.mjs example.com` from this skill folder (Node 20+). Require nonempty parseable JSON with the expected `domain`, `observedAt` and `records`; exit code zero with empty output is a failed run. It changes nothing and cannot discover forwarding destinations, arbitrary DKIM selectors or the full zone. Failed lookups are unknown. `no_records` applies only to the requested RR type, not absence of the DNS name or CNAME. Do not use its output as a complete zone snapshot.

## 2. Plan and check access

Read [the current workflow contract](references/workflow.md) before changes. Produce a small per-address plan: current destination → intended destination, product/workspace, DNS additions/conflicts, sender capacity, rollback and remaining prerequisites.

- Use existing authenticated provider tools/browser sessions or locally supplied scoped credentials. Never request secrets in chat, print them, commit them, copy cookies to another service or install a remote script blindly.
- For browser work, use a directly relevant authorized provider tab or create your own task tab. Do not claim another agent's active tab. A browser timeout or missing DNS API scope is an access/tool checkpoint, not proof that configuration failed; preserve completed API steps and report the exact prerequisite to the operator.
- Check the actual provider plan and shared usage. Domain quotas and application allowances are separate. A second API key is not an isolated supplier subaccount. No purchases, plan upgrades, fake provider IDs or relaxed ownership checks to bypass a free limit.
- Proceed with changes already covered by user authorization. If the concrete plan would drop an existing forwarding destination, replace an unknown MX service, add cost or exceed scope, resolve that conflict first. Do not ask again for routine steps already authorized.

## 3. Configure and read back

- Reuse matching entries; create only missing product/domain/address bindings. Never recreate an existing domain claim just to read its challenge. Keep exact address spelling/case returned by the service.
- Obtain ownership TXT and supplier DKIM/return-path records from the current authenticated service/provider, never from examples. Add only missing, non-conflicting records. Preserve existing SPF senders and other DKIM selectors; never add a second SPF policy. Read back both authoritative configuration and public DNS.
- Before replacing an exact existing forward with the Worker, require the operator to configure and read back its exact original destination through `/api/mailbox/forwarding`. The Worker now supports stored preservation policies, including forwarding when local storage fails or exceeds its size limit. Do not alter MX, catch-all or unrelated sender rules. Confirm actual delivery to both the service and the original destination; a saved policy or accepted forwarding API call is insufficient. Duplicate same-recipient rules are not a fan-out mechanism. Restore the original provider rule before suspending or transferring the mailbox.
- Capture activation versions before external checks. Only an authorized operator activates the domain transport after verifying ownership/provider/routing; exact recipient readiness follows an actual stored external arrival. A stale version or ambiguous mutation response requires readback and reassessment, not a fresh version pasted onto old evidence.
- After each mutation save the resulting ID/version in the private journal. After a timeout search/read back before retrying. Scoped `apply` reuses its exact product and bindings; raw product-creation POSTs must not be blindly repeated. `verify` resumes an already verified claim without a redundant DNS query. Keep completed steps and resume from observed state.

## 4. Acceptance and handoff

For each new exact recipient, prove an authorized external message arrives in the correct product/workspace. Reply from the original receiving identity; inspect the external recipient's actual receipt and thread. Send a separately authorized new message and confirm Sent persists after reload. Check From/Reply-To and reply references. One positive domain check does not establish every alias.

Record provider acceptance, external receipt and initial inbox/spam placement separately. If the recipient moves the message out of spam, retain its initial placement. Do not claim delivery from an HTTP success or readiness flag. On an ambiguous send keep its original request key and recover that attempt; do not generate another send. Retry only after a known failure and a checked correction, at most once per corrected condition before reporting the blocker.

A transient `mailbox_storage_pending` on a read can be checked again with the same read operation after recovery; never resend an already submitted test to fix a read failure. When the source and old forwarding destination are the same Gmail account, Gmail may show only its Sent original. That is not forwarding evidence. Arrange one separately authorized test from another controlled sender and inspect the old destination's actual delivery headers. Do not broaden a setup grant just to read unrelated mail.

A route saved by the provider may not yet be serving mail. If a uniquely identified test is missing, inspect that exact provider event before retrying. Record old-forward versus Worker handling separately. After a confirmed correction or propagation, allow at most one separately identified probe; do not repeatedly send while the outcome is unknown.

When a grant expires or is revoked with an unresolved send, retain its grant ID and original client key. Ask the authorized operator to recover the original receipt through the owner-only recovery path; a replacement grant cannot recover that attempt. Do not renew or resend automatically. At acceptance completion, have the operator revoke setup access and read back revocation; ordinary mailbox service must remain available.

Return a compact checklist per address: configured, receiving proven, reply proven, new-send proven, Sent persisted, initial placement, old forwarding configuration preserved, old destination delivery tested, and the next specific action if pending. A preserved rule is not proof of delivery. Use `pending` or `blocked` for missing evidence; never convert a local test, a saved rule or an operator handoff into “connected”.