# Example Workflows {#example-workflows}


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.



---


## Operational email flows {#operational-email-flows}


For an event-triggered receipt or an internal operational alert, set
`transactional: true` on the email step in the initial `nitro_compose_flow`
request. Leave it omitted for marketing, including promotional follow-ups.
For example:

```json
{
  "composition_mode": "intent",
  "name": "Shipping needs attention",
  "goal": "Notify our operations mailbox when an order needs shipping attention",
  "trigger": { "event": "shipping_attention" },
  "steps": [{
    "type": "email",
    "key": "shipping_alert",
    "transactional": true,
    "subject": "Shipping needs attention",
    "body": "An order needs your attention. Open the shipping dashboard."
  }]
}
```

Follow the returned `next_call` to finish the draft. Nitrosend preserves that
step's classification while you edit its copy; do not add the flag to the
returned copy draft. New steps default to marketing. Existing flows and
contacts retain their current settings. Review and activate the completed flow
through `nitro_control_delivery`.

Operational email does not require marketing subscription, but hard
suppression, account restrictions, content review and sending limits still
apply. Marking promotional email as transactional does not authorize it.


## Example 1: Check account health {#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):

```json
{}
```

**Response:**

```json
{
  "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"` and `params: { "subdomain": "<name>" }`,
the name it chooses for `hello@<name>.nitrosend.net`. Without a subdomain the
name derives from the company name and needs the complete Brand Kit. 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:

```json
{
  "brand_sid": "1a2b3c4d5e6f708192837465"
}
```

The AI calls `nitro_select_brand` with that SID. Future calls use that brand, within the [access chosen when connecting](https://docs.nitrosend.com/integrations/overview.md#choose-connection-access). API key connections stay with the API key's brand.

---


## Example 2: Create and send an email campaign {#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`:**

```json
{
  "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:**

```json
{
  "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:
   ```json
   {"target_type": "campaign", "target_id": 7, "operation": "approve"}
   ```
   Then:
   ```json
   {"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`:

```json
{
  "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. Under Safe Mode, an email campaign send from any connected agent, by sign-in or API key, waits for the account owner or an admin to approve its exact content and audience in Nitrosend, and an agent's flow and SMS live/schedule calls are blocked. `confirm_send_to_all` only confirms that the broad all-subscribed-contacts audience is intentional.

---


## Example 3: Build a welcome automation flow {#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`:**

```json
{
  "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:**

```json
{
  "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 {#example-4-bulk-tag-contacts}


**You say:**

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

**AI calls `nitro_manage_audience`:**

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

**Response:**

```json
{
  "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 {#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](https://docs.nitrosend.com/guides/agent-payments.md) has complete MCP, CLI, and REST
flows. [Purchase lifecycle](https://docs.nitrosend.com/concepts/payment-lifecycle.md) explains approval,
idempotency, provider routing, and completion proof. Use the [MCP tools
reference](https://docs.nitrosend.com/mcp.md) for the current request and response fields.

---


## What's next {#whats-next}


- [Connect your AI tool](https://docs.nitrosend.com/integrations/overview.md) — setup guides for Claude, ChatGPT, Gemini, Cursor, and more
- [Brand Kit & AI Memory](https://docs.nitrosend.com/integrations/mcp-brand-kit-memory.md) — teach your AI your brand voice and strategy
- [API Reference](https://docs.nitrosend.com/api.md) — full REST API documentation
