Which entity type to query. Use nitro_search_contacts for full-text contact search.

Entity-specific filters. All entities support id (integer) to fetch a single record.

• flows — status (draft/active/paused/archived), campaign_id (integer|null), trigger_event (string), search (string)
• campaigns — status (draft/active/paused/completed), search (string)
• templates — subject (string, ILIKE match on subject line)
• segments — name (string, ILIKE match)
• contacts — query (string, full-text search), subscribed_email (boolean), subscribed_phone (boolean), list_id (integer)
• lists — name (string, ILIKE match)
• events — name (string, exact event type), from (ISO 8601 datetime), to (ISO 8601 datetime)
• imports — status (pending/processing/completed/failed)
• messages — channel (email/sms), status (queued/sent/failed), to (string, recipient address)

Page number (default 1)

Results per page (max 50, default 25)

Email address, name, or phone number

summary = list, profile = single contact detail (default: summary)

Page number (default 1)

Results per page (max 50, default 25)

Website URL to scrape brand from

Direct URL to a logo image (png/jpg/webp/svg) to attach — SVGs are auto-converted to PNG

Direct brand field updates

Full brand voice markdown document

Preview changes without persisting

sync (default) or async for URL scraping

Optional dedup key

Which audience operation to perform. Each operation expects specific params:

• create_contact — params: {email (string), phone (string), opt_in (boolean, recommended: true), attributes: {first_name, last_name, country_code, source}}
• set_subscription — params: {contact_id (required), kind: "email"|"phone" (required), opt_in (boolean), opt_out (boolean), unsubscribe_all (boolean)}. Value auto-resolved from contact.
• manage_list — params: {action: "create"|"rename"|"delete"|"add_contacts"|"remove_contacts" (required), list_id (integer), name (string), contact_ids (integer[]) or emails (string[])}
• record_event — params: {contact_id or contact_email (one required), event (required, custom names allowed e.g. order_confirmed), data (object, max 32KB), resource_uid, resource_name, resource_url, amount}
• delete_segment — params: {segment_id (required), force (boolean)}. Requires confirm: true.
• bulk_tag — params: {contact_ids (integer[], required), tags (string[], required), tag_action: "add"|"remove"|"set" (default: "add")}

Operation-specific parameters. See operation description for required/optional fields.

Preview changes without persisting (default: false)

Required for destructive operations: delete_segment, manage_list with action='delete'

Optional deduplication key. Same key returns cached result.

Segment name (required when preview_only: false)

Array of filter objects. Each filter has:

• name — filter alias from flows.yml (e.g. "contact_email", "contact_first_name", "contact_country", "contact_subscribed_email", "contact_created_at", "contact_tag")
• predicate — Ransack predicate — eq, not_eq, cont, not_cont, start, end, gt, lt, gteq, lteq, present, blank, true, false, in, not_in
• value — filter value (string, number, boolean, or array for in/not_in). For present/blank/true/false predicates, pass true.

Existing segment ID to update (omit for new segment)

Only preview matching contacts, do not save (default: true). Set to false + provide name to persist.

Optional deduplication key

Array of contact objects (max 100): {email, phone, first_name, last_name, country_code, source, opt_in}

Existing Import record ID for CSV processing

Preview import without persisting (default: false)

Optional deduplication key

Array of section objects: {type, props, styles?}. Read nitro://schema for full prop specs.

Section types and key props:

• header — {logo_url, logo_alt, logo_width, background_color}
• text — {content (HTML string)}
• image — {src, alt, href, width}
• button — {text, href, background_color, text_color, align, border_radius}
• columns — {columns: [{width, sections: [...]}]} — nested sections inside columns
• product — {name, price, image_url, href, description}
• social — {links: [{platform, url}], align}
• divider — {color, width, padding}
• spacer — {height}
• footer — {company_name, address, unsubscribe_text}

Email subject line (recommended under 60 chars)

Template display name

Email preheader text shown in inbox preview

Sender name (falls back to account default)

Sender email (falls back to account default)

Reply-to email address

Theme overrides merged on top of brand theme. Keys: brand_color (hex), bg_color (hex), text_color (hex), font_body (string), font_heading (string), logo_url (URL)

Template ID for update mode — provide with fields to change

Source template ID for clone mode — creates a copy

Optimistic concurrency — rejects update if template version mismatches

Goal-driven composition (Phase 5 — not yet available)

Validate and preview without persisting

Dedup key — same key returns cached result

Flow name (required for create mode)

create: new flow; replace: rebuild existing flow graph; patch: metadata only

Required for replace/patch modes

Goal string for AI generation (Phase 5C — feature gated)

Ordered array of flow steps. Required props per type:

• email — subject (required), design ({sections, theme}) or body, preheader, from_name, from_email, reply_to, transactional (boolean), bcc (string, optional BCC email address)
• sms — body (required)
• wait — duration (integer, seconds — e.g. 86400 = 1 day)
• split — filters (required, [{name, predicate, value}]), yes (steps array), no (steps array). NO nested splits.
• emit_event — event_name (required), event_data (object), forward_event_data (boolean)
• webhook — url (required), method (POST or PUT, default POST), headers (object), body (template string with merge tags)
• subscribe — channel (phone, email, or all — default phone). Subscribes the contact.
• unsubscribe — channel (phone, email, or all — default phone). Unsubscribes the contact.

Preview graph without persisting

Deduplication key for retry safety

Required for replace mode

Campaign name

Auto-detected as 'email' when sections or template_id provided. Set explicitly to 'sms' for SMS campaigns.

Goal string for AI generation (Phase 5C — feature gated)

Email subject line (email campaigns)

Email preheader (email campaigns)

Sender name override

Sender email override

Reply-to email override

SMS body text (sms campaigns) or email plain text

Email design sections array — same format as nitro_manage_template. Requires subject.

Email theme overrides merged on brand theme: {brand_color, bg_color, text_color, font_body, font_heading, logo_url}

Clone design from existing template (email campaigns)

Target audience for the campaign. Use audience_type='all_contacts' only for an explicit all-subscribed-contacts send.

ISO 8601 delivery time (e.g. '2026-03-01T10:00:00Z'). Omit for manual send.

Preview campaign without creating (default: false)

Optional deduplication key

Which domain operation to perform:

• add — params: {domain_name (required, e.g. "send.acme.com")}. Registers domain with email provider and returns DNS records. The user must add these DNS records at their domain registrar. Idempotent: calling add on a pending domain re-returns the DNS records.
• verify — params: {domain_name (required)}. Checks with the email provider if the core DNS records have propagated. Also runs independent DNS validation and returns per-record dns_health. Optional records like tracking are reported separately and do not block completion. If verified, completes the domain_verified onboarding step and unlocks sending. If still pending, returns the DNS records again so you can re-show them to the user.
• check_dns — params: {domain_name (required)}. Runs independent DNS validation only. Does not call the email provider. Useful for diagnosing missing or incorrect customer-facing records and Nitro-managed delegate targets before verify. Optional improvements are surfaced without blocking setup completion.
• list — no params needed. Returns all account domains with their verification status and DNS records. Includes dns_health, dmarc_policy, domain_limit (from tier), and domains_used count.
• remove — params: {domain_name (required)}. Deletes the domain. Requires confirm: true.

Operation-specific parameters.

Required for remove operation (destructive)

Sender display name (e.g. 'Acme Marketing')

Sender email address (must match a verified domain)

Reply-to email address

Saved email addresses for test sends (max 5). Pass empty array to clear.

Entity type to review

Entity ID to review

Optional contact ID for merge-tag personalization during review

Target entity type. Use with target_id unless latest_campaign or template_id is used.

Target entity ID. Use with target_type.

Use the most recently created campaign in this brand.

Template to test directly, or the specific flow/campaign template to choose.

Flow action ID to test when a flow has multiple message steps.

Channel to test. Use auto unless a standalone template is ambiguous.

Contact ID for recipient and merge-tag personalization. If present, this contact supplies the recipient address/phone.

Explicit test recipients. Use email addresses for email targets and E.164 phone numbers for SMS targets.

Validate target and recipients without sending.

Optional deduplication key for retry safety.

Entity type

Entity ID

Lifecycle operation. approve runs preflight. schedule is campaign-only (requires scheduled_at). Most require prior approval.

Required for schedule operation (ISO 8601 datetime)

Required when making a campaign live or scheduled with audience_type='all_contacts'. Forces an explicit all-subscribed-contacts confirmation.

Scope of insights: account-wide, per flow, per campaign, or per message

Required for flow/campaign/message scope

Time period for metrics (default 30d)

configure sets BYO provider credentials; status checks current provider health

Email provider (required for configure)

Provider API key (required for configure, never returned in responses)

Optional provider secret (never returned in responses)

Optional provider region, e.g. us-east-1

read: get current document. update: replace entirely. patch: replace a ## section by heading. append: add text to end.

Full markdown document (required for update).

Section heading to patch (e.g. 'Brand Goals'). Required for patch operation. Matches ## headings.