Tools & examples

Jump to a domain

• Orders (9) · Balance (4) · Catalog (4)
• Recipients (6) · Recipient Groups (7)
• Campaigns (6) · Templates (5)
• Draft / Execute (2) · CSV (2) · Credentials (1) · Limits (1)

Orders — 9 tools

Send branded cards (fixed brand), choice cards (recipient picks), or anonymous reward links. All create_*_order calls are idempotent and subject to the per-org daily USD spend cap.

Balance — 4 tools

Inspect your prepaid USD balance and ledger, request an ACH top-up, or withdraw a pending top-up request. Credit card top-ups require signing in to the Giftronaut portal and cannot be completed through MCP.

Catalog — 4 tools

Browse what you can send. Catalog tools never touch funds — they only return product metadata.

Recipients — 6 tools

Manage your organization's recipient list. Emails are AES-encrypted at rest — for exact-email lookup use find_recipient_by_email rather than list with a searchKeyword.

Recipient Groups — 7 tools

Named buckets for campaign targeting (e.g. "Engineering", "Q4 VIPs", "Holiday Recipients 2026"). Renaming a group preserves all members; deleting a group preserves the individual recipients — only membership rows are dropped. The new giftronaut_update_recipient_group tool lets the LLM rename a group on the fly (the only mutable field) — useful when a group is re-purposed mid-campaign (e.g. "rename 'Q4 VIPs' to 'Annual VIPs'" before the year rolls over).

Campaigns — 6 tools

A campaign is a reusable, named template for sending choice cards — it bundles the product, per-recipient amount, subject line, sender display name, message body, attached email template, and refund policy into a single addressable unit. Once saved, the campaign can be executed for any recipient (inline recipient list OR a saved recipient group) with a single giftronaut_execute_campaign_order call.

Use campaigns for recurring sends where the configuration stays stable but the audience changes — monthly bonus drops, quarterly partner appreciation, recurring referral rewards, holiday greetings. For one-off sends use giftronaut_create_choice_card_order or giftronaut_create_branded_card_order instead.

Important properties:

• All campaigns are Choice Card (USD 1:1) — branded-card campaigns are not supported via this API surface. Use the one-off giftronaut_create_branded_card_order tool for branded sends.
• Creating/updating/deleting a campaign does NOT move funds — only giftronaut_execute_campaign_order debits balance.
• Soft delete — giftronaut_delete_campaign sets IS_DELETED=1; past order history that references the campaign is preserved and remains queryable via giftronaut_list_orders.
• Per-execute overrides — senderName, subject, and message can be overridden on a single execute call without touching the saved campaign.
• Guards — execute is subject to GeoIP country allowlist, daily USD spend cap, and balance check. Insufficient balance returns INSUFFICIENT_BALANCE (402) with a structured top-up hint.

Templates — 5 tools

A template defines the visual style of a gift-card delivery email — the logo image URL, button color palette, sender display name, and an optional plaintext message body. Every order or campaign references a template via templateId; when null, the org's default template is auto-attached at send time. Templates let you maintain brand consistency across all gift-card emails without re-specifying the visuals on every send.

Color fields (borderColor, buttonColor, buttonFontColor) are 6-digit hex strings in #RRGGBB format. imageAlignment is one of left · center · right. imageSize is a pixel dimension. The logo image URL itself is auto-populated server-side to the default Giftronaut asset — custom logo uploads require the portal.

Important properties:

• The isDefault flag is portal-managed — it cannot be flipped via giftronaut_create_template or giftronaut_update_template. The default template is auto-attached to any order/campaign that omits templateId.
• PUT-semantics update — giftronaut_update_template replaces ALL optional fields with the supplied values (or server defaults if omitted). Fetch via giftronaut_get_template first to preserve current settings.
• Delete is hard (not soft) and blocked by two service-level guards — see the callout below the table.
• Message body is plain text only, max 2000 chars. HTML is NOT supported here — the visual style around the body comes from the template's color palette and the system's email scaffold.

Draft / Execute — 2 tools

A 2-step pattern that your AI assistant may use to protect you from accidental sends. When used, the draft is created first without moving funds — you review it, then confirm. The assistant decides whether to use this pattern based on the context.

CSV — 2 tools

Bulk recipient import. Parse first to detect duplicates and validation errors, then batch-create up to 100 rows per call. Cells are sanitized for prompt-injection markers before validation.

Credentials — 1 tool

Creates a sandbox credential for REST API use only — MCP itself is production-only, so the created sandbox credential cannot be used to connect MCP. Production apps are created in the portal (Apps → Create new app → Production) and are active immediately for MCP delegation.

Limits — 1 tool

Use when an organization admin asks to raise their daily and/or monthly order spending limit. Submits a limit-increase request to the operations team for review (approval typically within 1-2 business days) — the new limit is NOT applied immediately. Requires the current daily and monthly limits (as the user currently sees them, used purely as a confirmation check) plus the requested new daily and monthly limits, all in USD. If the supplied current limits do not match our records, the request is rejected with STALE_LIMIT_SNAPSHOT (409) so you can refresh and retry. Each requested limit must be greater than the current limit. Returns status PENDING_REVIEW with a confirmation message. Idempotent via idempotencyKey (24h cache).

Parameters (all required):

• idempotencyKey · Unique idempotency key (max 64 chars). Reuse to safely retry the same request — the 24h cache returns the original response.
• currentDailyLimitUsd · Your current daily order limit in USD, exactly as shown to you (confirmation check). Pass as a decimal, e.g. 500.
• currentMonthlyLimitUsd · Your current monthly order limit in USD, exactly as shown to you (confirmation check). Pass as a decimal, e.g. 4000.
• requestedDailyLimitUsd · The requested new daily order limit in USD. Must be greater than the current daily limit.
• requestedMonthlyLimitUsd · The requested new monthly order limit in USD. Must be greater than the current monthly limit.

Common behaviors

• Idempotency · Tools with idempotentHint=true accept an idempotencyKey. The 4-tuple (org_id, env, tool_name, key) is cached for 24 hours; retries replay the original response.
• Spend cap · Every value-moving tool checks the daily USD cap before invoking the service. Exceeding it returns { "code": "DAILY_SPEND_CAP_EXCEEDED", "status": 429 }.
• Kill switch · Operators can disable individual tools per environment. Disabled tools return { "code": "TOOL_DISABLED", "status": 503 } and are hidden from tools/list.
• Cross-org guard · All queries are filtered by org_id. Requesting another org's resource returns RESOURCE_NOT_FOUND.

Full parameter reference: tools-reference.md (canonical markdown source).