Home
Guides

Example Workflows

Complete prompt-to-result examples showing how AI tools use Nitrosend via MCP

These examples show the full loop: what you say, what your AI calls, and what comes back. Every tool call uses real parameter names and realistic response data.

Tip

These examples work with any MCP-connected AI tool — Claude, ChatGPT, Codex, Gemini, Cursor, and more. The tool calls are identical across all clients.

Example 1: Check account health

You say:

What's my Nitrosend account status? Is anything blocking me from sending?

AI calls nitro_get_status (no parameters):

{}

Response:

{
  "result": {
    "status": "needs_attention",
    "current_brand": {
      "sid": "8f1e2d3c4b5a69788796a5b4",
      "name": "Acme Co",
      "company_name": "Acme Co",
      "context_source": "oauth_selection"
    },
    "available_brands": {
      "items": [
        { "sid": "8f1e2d3c4b5a69788796a5b4", "name": "Acme Co", "is_current": true },
        { "sid": "1a2b3c4d5e6f708192837465", "name": "Acme Outlet" }
      ],
      "returned": 2,
      "limit": 25
    },
    "available_brands_truncated": false,
    "account": {
      "tier": "free"
    },
    "brand": {
      "sid": "8f1e2d3c4b5a69788796a5b4",
      "name": "Acme Co",
      "setup_complete": false,
      "company_name": "Acme Co",
      "can_send": false,
      "domain_verified": false,
      "contact_count": 45,
      "flow_count": 1,
      "campaign_count": 2
    },
    "brand_subdomain": {
      "namespace_status": "active",
      "status": "not_materialized",
      "ready": false,
      "preparation_required": true,
      "fqdn": "acme-co.nitrosend.net",
      "apex": "nitrosend.net",
      "local_part": "hello",
      "local_part_editable": false,
      "fqdn_changeable": false
    },
    "billing": {
      "tier": "free",
      "resources": {
        "email": { "used": 12, "allowance": 500, "mode": "monthly" },
        "sms": { "used": 0, "allowance": 50, "mode": "lifetime" },
        "ai": { "used": 3, "allowance": 20, "mode": "monthly" }
      }
    },
    "delivery": {
      "assessment_scope": "account_capacity",
      "admission_status": "denied",
      "commercial_capacity": {
        "status": "known",
        "limit": 50,
        "reserved": 0,
        "accepted": 12,
        "provider_unknown": 0,
        "remaining": 38
      },
      "pacing_state": {
        "status": "ready",
        "policy_version": "delivery-pacing-v3",
        "scopes": []
      },
      "blocking_control": "sender_identity",
      "reason_code": "sender_not_ready"
    },
    "issues": [
      {
        "area": "domain",
        "severity": "high",
        "message": "No ready sending identity. Activate your reserved Nitrosend brand subdomain, or verify a custom domain.",
        "brand_subdomain_status": "not_materialized",
        "brand_subdomain_preparation_required": true,
        "blocks": "campaign approval and live sends"
      }
    ],
    "recommendations": [
      { "action": "Set physical address", "tool": "nitro_set_brand_kit" },
      { "action": "Activate or verify a sending identity", "tool": "nitro_manage_domains" }
    ]
  },
  "meta": {
    "tool": "nitro_get_status",
    "current_brand": { "sid": "8f1e2d3c4b5a69788796a5b4", "name": "Acme Co" }
  }
}

What happens next: The AI reads the structured identity state and asks to activate the permanently reserved sender or connect a customer-owned domain. For the Nitrosend path it calls nitro_manage_domains with operation: "prepare_brand_subdomain". That operation materializes the local identity synchronously and selects it only when no sender is already selected. If another sender remains selected, the agent then calls operation: "select_brand_subdomain" explicitly. Activation retains no email and performs no provider work.

For accounts with multiple brands, switch context before making changes:

{
  "brand_sid": "1a2b3c4d5e6f708192837465"
}

The AI calls nitro_select_brand with that SID. Future OAuth MCP tool calls use that brand. API key connections are pinned to the API key's brand and cannot switch.

Example 2: Create and send an email campaign

You say:

Create a spring sale campaign for my Newsletter list with a hero banner, sale announcement, and a Shop Now button.

Step 1 — AI calls nitro_compose_campaign:

{
  "name": "Spring Sale 2026",
  "subject": "Spring Sale — 30% off everything",
  "sections": [
    { "type": "header", "props": {} },
    {
      "type": "hero",
      "props": {
        "image_url": "https://images.unsplash.com/photo-spring-flowers",
        "title": "Spring Sale",
        "subtitle": "30% off everything this week",
        "cta_text": "Shop Now",
        "cta_url": "https://store.example.com/sale"
      }
    },
    {
      "type": "text",
      "props": {
        "content": "<p>Hi {{ contact.first_name }},</p><p>Our biggest sale of the season is here. Everything in the store is 30% off through Sunday.</p>"
      }
    },
    {
      "type": "button",
      "props": {
        "text": "Shop the Sale",
        "href": "https://store.example.com/sale"
      }
    },
    { "type": "footer", "props": {} }
  ],
  "audience": {
    "audience_type": "lists",
    "contact_list_id": 42
  }
}

Response:

{
  "result": {
    "campaign_id": 7,
    "template_id": 15,
    "flow_id": 22,
    "status": "draft",
    "audience_count": 1250
  }
}
1

Preview

AI calls nitro_review_delivery with {"target_type": "campaign", "target_id": 7} and shares the preview URL so you can review the email visually.

2

Test

If you want an inbox check first, AI calls nitro_send_test_message with {"target_type": "campaign", "target_id": 7, "to": ["you@example.com"]}. This sends only to the test recipient, not the campaign audience.

3

You confirm

You say "Looks good, send it."

4

Approve and send

AI calls nitro_control_delivery twice:

{"target_type": "campaign", "target_id": 7, "operation": "approve"}

Then:

{"target_type": "campaign", "target_id": 7, "operation": "live"}

Campaign goes live and starts sending to 1,250 contacts.

If the campaign audience is all_contacts, the final call must include confirm_send_to_all:

{
  "target_type": "campaign",
  "target_id": 7,
  "operation": "live",
  "confirm_send_to_all": true
}

Approval, Safe Mode, and confirm_send_to_all are separate checks. Approval verifies content and preflight readiness. Safe Mode can still block API-key live/schedule calls. confirm_send_to_all only confirms that the broad all-subscribed-contacts audience is intentional.

Example 3: Build a welcome automation flow

You say:

Set up a welcome series: when someone joins my Subscribers list, send a welcome email immediately, wait 3 days, then send a follow-up with tips.

AI calls nitro_compose_flow:

{
  "name": "Welcome Series",
  "trigger": {
    "event": "list_add",
    "contact_list_id": 5
  },
  "steps": [
    {
      "type": "email",
      "subject": "Welcome aboard!",
      "design": {
        "sections": [
          { "type": "header", "props": {} },
          {
            "type": "text",
            "props": {
              "content": "<h1>Welcome, {{ contact.first_name }}!</h1><p>We're excited to have you. Here's what to expect from us.</p>"
            }
          },
          {
            "type": "button",
            "props": {
              "text": "Get Started",
              "href": "https://example.com/start"
            }
          },
          { "type": "footer", "props": {} }
        ]
      }
    },
    {
      "type": "wait",
      "duration": 259200
    },
    {
      "type": "email",
      "subject": "3 tips to get the most out of Example",
      "design": {
        "sections": [
          { "type": "header", "props": {} },
          {
            "type": "text",
            "props": {
              "content": "<h1>Quick tips</h1><p>Here are 3 things our most successful users do in their first week:</p><ol><li>Complete your profile</li><li>Invite a teammate</li><li>Set up your first project</li></ol>"
            }
          },
          { "type": "footer", "props": {} }
        ]
      }
    }
  ]
}

Response:

{
  "result": {
    "id": 12,
    "draft_revision_id": 42,
    "step_count": 3,
    "status": "draft",
    "trigger": { "event": "list_add", "contact_list_id": 5 }
  }
}

What happens next: The flow is in draft. AI copies the flow ID from result.id and the exact current revision from result.draft_revision_id in the persisted nitro_compose_flow response. It calls nitro_review_delivery with {"target_type": "flow", "target_id": 12, "revision_id": 42}. When review returns result.revision_id as 42, AI copies that review-returned value into both control calls: {"target_type": "flow", "target_id": 12, "operation": "approve", "revision_id": 42} and then {"target_type": "flow", "target_id": 12, "operation": "live", "revision_id": 42}. From now on, every contact added to the Subscribers list automatically receives the welcome series.

Example 4: Bulk-tag contacts

You say:

Tag contacts 101, 102, and 103 as vip and newsletter.

AI calls nitro_manage_audience:

{
  "operation": "bulk_tag",
  "params": {
    "contact_ids": [101, 102, 103],
    "tags": ["vip", "newsletter"],
    "tag_action": "add"
  }
}

Response:

{
  "result": {
    "dry_run": false,
    "updated": 3,
    "tags": ["vip", "newsletter"],
    "action": "add"
  }
}

What happens next: Each contact's existing tags are merged with vip and newsletter (no duplicates). Use tag_action: "remove" to strip tags, or tag_action: "set" to replace each contact's tag list entirely. Pass dry_run: true to preview — the response then returns contact_count (how many would be affected) instead of updated, and persists nothing.

Tip

To tag by email instead of ID, first call nitro_search_contacts to resolve emails → contact IDs, then pass the IDs into bulk_tag. The tool intentionally requires contact_ids so an empty filter can't accidentally tag every contact in the brand.

Buy a plan or add prepaid funds

Plan purchase and prepaid funding share nitro_manage_billing, but they remain separate lifecycles. Start with status, ask the account owner to approve the exact plan or amount, and pass a stable idempotency_key when you create the purchase. If Nitrosend returns an approval URL, hand it to the owner and poll Nitrosend afterward. A plan is complete at active; prepaid funding is complete at credited.

Payments for agents has complete MCP, CLI, and REST flows. Purchase lifecycle explains approval, idempotency, provider routing, and completion proof. Use the MCP tools reference for the current request and response fields.

What's next

Docs by Sourcey
Edit this page