# Agent Onboarding {#agent-onboarding}


Nitrosend is built MCP-first, so an AI agent can run the whole email stack — campaigns, flows, contacts, transactional sends, deliverability — as native tools. This page is the human-readable overview. The full, machine-readable onboarding skill lives in a single file your agent can fetch and follow:







**[nitrosend.com/SKILL.md](https://nitrosend.com/SKILL.md)**

The canonical agent onboarding skill: vocabulary, every public `nitro_*` tool, send modes, the response envelope, the delivery lifecycle, and the headless signup-to-send path. Point your agent here.






## Two ways in {#two-ways-in}








**MCP (recommended)**

Connect the MCP server and the agent gets the full public tool set. Best for Claude, ChatGPT, Cursor, Codex, Gemini, v0, and any MCP client.






**Headless REST**

For builder stacks with no MCP client (Replit, Lovable, Bolt) or CI runners: sign up, mint a key, and send over plain HTTP.






## MCP path {#mcp-path}


One command (or, in Claude Desktop and Claude.ai, the official Nitrosend connector under **Settings → Connectors**) plus OAuth sign-in:

```bash
claude mcp add --transport http nitrosend https://api.nitrosend.com/mcp
```

Call `nitro_get_status` first for account context, then read the `nitro://guide` resource. Full per-client setup is in the [Quickstart](https://docs.nitrosend.com/quickstart.md) and [MCP integrations](https://docs.nitrosend.com/integrations/overview.md).

During sign-in, you can [restrict the connection to one account or brand](https://docs.nitrosend.com/integrations/overview.md#choose-connection-access). The restriction applies to every chat using that connection; existing connections keep their current access.


## Headless path (no dashboard, no MCP client) {#headless-path-no-dashboard-no-mcp-client}


Request bodies on this path are top-level JSON fields; only signup nests its fields, under `user`. `PATCH /v1/my/brands/{sid}` with `{ "company_name": "Acme" }` sets the company name, while `{ "brand": { "company_name": "Acme" } }` returns `200` and changes nothing.



1. **Begin signup and verify email**

   `POST /v1/signup` with `{ "user": { "email": "you@example.com" } }` returns HTTP `409` with `status: "verification_required"`, `error_code: "verification_required"` and `next_action: "verify_email"`. It creates no account or session yet. Read the email, then explicitly `POST /v1/signup/verify` with `{ "token": "email-token", "password": "final-password" }`. That password is the one the account uses, and it replaces any `password` sent at signup, which is optional. Success returns HTTP `200`, the user and `meta.account_id`, and a JWT in the `Authorization` response header. No browser or CAPTCHA is required.

2. **Mint an API key**

   `POST /v1/my/api_keys` with that JWT. The response includes the full `nskey_live_...` secret once, in `secret_key`. Store it as a secret then. Later reads mask it; reveal it again with `GET /v1/my/api_keys/{id}?reveal=true`.

3. **Activate the reserved sender**

   Get the brand SID from `GET /v1/my/brands`, then call `POST /v1/my/brands/{sid}/prepare_sending` with `{ "subdomain": "<name>" }` (optionally `"local_part"`, which defaults to `hello`). It reserves `<name>.nitrosend.net` for the brand, permanently, and materializes its local Domain and sending-identity rows synchronously under Nitrosend's verified shared root. The brand's `brand_subdomain.suggested_subdomain`, when present, is a safe starting name; if the call returns `subdomain_taken`, choose another. Without a `subdomain`, the call derives the name from the company name instead and refuses with `brand_identity_required` until the whole Brand Kit is complete. Once a name is reserved, repeat calls return it and ignore the body. The sender can send when the response `status` is `ready`. It creates no per-brand DNS, DKIM, provider identity, tenant resource, or background job. When no sender is selected, the same transaction selects this sender; otherwise it preserves the existing selection.

4. **Send once ready**

   `POST /v1/my/messages` with `{ "channel": "email", "to", "subject", "html" }` and an `Idempotency-Key` header. If the previous step was skipped, an eligible first request performs the company-derived materialization before admission, which needs the complete Brand Kit. If the shared root is unavailable, the API returns retryable `hosted_sender_root_unavailable`, stores no message, reservation, charge, or provider capability, and the same request is safe to retry.

5. **Choose optional production upgrades**

   A customer-owned sending subdomain builds portable reputation and never consumes the reserved Nitrosend brand-subdomain sender. Paid plans and checkout remain optional; `$0` plans need no card.



Links expire in 30 minutes and are used once. `POST /v1/signup/resend` with `{ "email": "you@example.com" }` returns a generic `202`; it is limited to three requests per address per UTC day and a one-minute cooldown, with a global daily mail budget. Resending preserves an unexpired link. If proof succeeded but activation or client storage failed, `POST /v1/signup/activate` with `{ "email": "you@example.com", "password": "final-password" }` returns the active session without creating another account. Respect `Retry-After` on `429`; keep working credentials until completion. An existing address gets the same signup response; established users can sign in normally.

To drive the [CLI](https://docs.nitrosend.com/cli/overview.md) from a runner with no browser, export the key as `NITROSEND_API_KEY` or store it with `nitrosend login --api-key <key>`. Plain `nitrosend login` opens a browser for OAuth.


## Managed customer accounts {#managed-customer-accounts}


For several brands that your team owns and pays for, keep using one account
and its brands. For isolated client-owned accounts, use the existing partner
API. CLI signup creates your own account; it does not provision a managed client.

An authorized agency manager first uses its direct user session to call
`POST /v1/my/account/provisioning_credentials` with `provision` and `manage`
scopes. Store this `nspk_live_` secret on your backend;
it is not a customer-data credential. Each customer's setup then uses:

1. `POST /v1/partner/managed_accounts`, with a stable `Idempotency-Key` and
   `managed_account: { external_ref, owner_email, account_name }`. Store the
   returned provisioning `id`. Replaying the same request returns the same
   account, and creation does not send an invitation.
2. `POST /v1/partner/managed_accounts/{id}/credentials`, with
   `credential: { name }`. Store the one-time `nsmc_live_` secret and returned
   `brand.sid`. This credential is restricted to that client and brand; it
   cannot mint keys, select another client or authorize purchases.
3. Use that client credential with the existing `/v1/my/domains`, inbox and
   webhook endpoints. Inbox access and domain ownership are still required.
   To use a subdomain of your own verified domain, its owner first
   [shares the exact subdomain with the client's brand](https://docs.nitrosend.com/guides/sending-domains.md#share-a-subdomain-with-another-brand-or-client).
   Your backend can do this with the domain owner's existing brand API key;
   use the destination `brand.sid` returned in step 2. The client credential
   finishes its own setup and cannot grant access to the parent domain.
   Continue normal DNS and inbox setup using the client credential. Several
   named inboxes can use that subdomain; each has its own sender name and mail.
   Receiving setup uses `PUT /v1/my/domains/{id}/inbound_setup`; select an existing
   inbox with `inbox_id` when the domain has several. Register `email.received`
   through `/v1/my/webhooks` and use its test and delivery-history endpoints to
   check your receiver.
4. When preparation is ready, use the provisioning credential to call
   `POST /v1/partner/managed_accounts/{id}/send_invitation`. The client owner
   must sign in, claim and pay through the existing flow. Preparation access
   ends at claim; consent alone does not authorize unpaid operation. Partner
   billing without a claim is not supported by this path.

Customer setup runs over HTTP without a browser login for each provisioning
request. Owner claim and payment remain separate requirements. Keep both secrets
out of frontend code and agent prompts. Test real inbound mail and a reply as
well as webhook receipt before treating a customer as ready. Read the received
conversation and reply through `POST /v1/my/conversations/{id}/reply`; connected
agents use `nitro_inbox` and `nitro_inbox_action` for the same journey. Nitrosend
selects the inbox sender and preserves the email thread. To start a conversation,
use `POST /v1/my/conversations` with a `conversation` containing `inbox_id`, `to`,
`subject` and `body`, plus an `Idempotency-Key` header. Connected agents use
`nitro_inbox_action` with `command: "compose"` and the same fields plus
`idempotency_key`. Set `dry_run: true` to preview without saving or sending;
omit it to send after approval. Optional `cc`, `bcc` and `attachment_refs` use
the same inbox delivery checks. Compose continues an open conversation with
that recipient. Keep the same key and payload when retrying; changes to the
sender, recipients or content require a new key. Verify webhook
signatures and deduplicate deliveries by `webhook-id`, including retries. The
[API schema](https://api.nitrosend.com/openapi.yaml) describes issuance,
revocation, expiration and the individual request bodies.

For the complete reference, always defer to [nitrosend.com/skill.md](https://nitrosend.com/skill.md) and the [REST API docs](https://docs.nitrosend.com/integrations/rest-api.md).
