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
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
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
One command (or, in Claude Desktop and Claude.ai, the official Nitrosend connector under Settings → Connectors) plus OAuth sign-in:
claude mcp add --transport http nitrosend https://api.nitrosend.com/mcpCall nitro_get_status first for account context, then read the nitro://guide resource. Full per-client setup is in the Quickstart and MCP integrations.
During sign-in, you can restrict the connection to one account or brand. The restriction applies to every chat using that connection; existing connections keep their current access.
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.
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.
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.
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.
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.
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 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
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:
POST /v1/partner/managed_accounts, with a stableIdempotency-Keyandmanaged_account: { external_ref, owner_email, account_name }. Store the returned provisioningid. Replaying the same request returns the same account, and creation does not send an invitation.POST /v1/partner/managed_accounts/{id}/credentials, withcredential: { name }. Store the one-timensmc_live_secret and returnedbrand.sid. This credential is restricted to that client and brand; it cannot mint keys, select another client or authorize purchases.- 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. Your backend can do this with the domain owner's existing brand API key; use the destinationbrand.sidreturned 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 usesPUT /v1/my/domains/{id}/inbound_setup; select an existing inbox withinbox_idwhen the domain has several. Registeremail.receivedthrough/v1/my/webhooksand use its test and delivery-history endpoints to check your receiver. - 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 describes issuance,
revocation, expiration and the individual request bodies.
For the complete reference, always defer to nitrosend.com/skill.md and the REST API docs.
