Integrate with AI agents

One-line install for coding agents

The flowmails-sdk skill is published to skills.sh. One command installs it into the agent’s skill library; after that, the SDK contract (Hard rules, the five error classes, retry policy, payload shapes, framework examples) is auto-injected into every session — the agent does not have to re-fetch any doc on every run.

npx skills add wms-why/flowmails-sdk-plugin@flowmails-sdk

The skill is the source of truth for the SDK’s call conventions. The HTML docs under /docs are the source of truth for the wire surface. Use both — the skill loads first, the doc is the fallback when something has just changed and the cached skill is one version behind.

New endpoints, error codes, or breaking changes to @flowmails/flowmails-sdk ship a matching skill update in the same release. The skill version tracks the SDK version (currently v0.1); npx skills update pulls the latest.

The five-line prompt

In any coding agent (Claude Code, Cursor, GitHub Copilot, Windsurf, Cody), paste this prompt. The agent will install the skill, internalize the SDK contract, and write the integration against @flowmails/flowmails-sdk.

Make sure the `flowmails-sdk` skill is installed by running:

  npx skills add wms-why/flowmails-sdk-plugin@flowmails-sdk

Then add a Flowmails client to this project using an API key from
the FLOWMAILS_API_KEY environment variable, and wire it up so I
can call fm.send() from any server-side route / handler / API
endpoint with a typed SendOptions payload.

Do NOT bypass the SDK with raw fetch / axios / curl — always
wrap with new Flowmails({...}).send({...}). Branch errors with
instanceof (AuthenticationError, ValidationError, RateLimitError,
UpstreamError, FlowmailsError). The full class hierarchy and the
HTTP → code matrix are baked into the skill.

The agent will: (1) install the skill, (2) pick up the exact constructor signature and class names, (3) wire the integration in one shot. No website crawl, no hallucinated method signatures, no missing retry policy.

Tool-specific setup

Claude Code

Run the install line directly in the chat — Claude Code will pick up the skill from your project’s installed skill list automatically. You can also persist the five-line prompt above as a custom slash command:

mkdir -p .claude/commands
# Paste the five-line prompt into this file:
cat > .claude/commands/flowmails.md <<'PROMPT'
Make sure the `flowmails-sdk` skill is installed by running:
  npx skills add wms-why/flowmails-sdk-plugin@flowmails-sdk
…
PROMPT

Cursor

Run the install line in your terminal so the skill lands in your global skill library. Cursor picks up globally installed skills automatically — reference flowmails-sdk in chat (e.g. “use the flowmails-sdk skill to wire up an SDK client”) and the agent loads the contract before responding.

GitHub Copilot (workspace)

Run the install line so the skill lands in the workspace toolchain. For agents that don’t speak the skills protocol, save the five-line prompt to .github/copilot-instructions.md — Copilot indexes that file automatically and pulls it into its prompt context.

mkdir -p .github
# Either install the skill (preferred):
npx skills add wms-why/flowmails-sdk-plugin@flowmails-sdk
# Or, for agents without skill support, write the prompt directly:
cat > .github/copilot-instructions.md <<'PROMPT'
Make sure the `flowmails-sdk` skill is installed by running:
  npx skills add wms-why/flowmails-sdk-plugin@flowmails-sdk
…
PROMPT

Anything else (Continue.dev, Cody, Windsurf, Aider…)

If the tool supports the skills protocol, npx skills add wms-why/flowmails-sdk-plugin@flowmails-sdk is enough — the skill auto-injects on every session. For tools without skill support, fetch the raw SKILL.md from the upstream repo and inline it as system context.

What the agent gets right (because of the skill)

• The exact class hierarchy. Five error classes extending FlowmailsError, each with the right HTTP status range and the right code strings. The agent will branch with instanceof, not by parsing the response body.
• The constructor options. All five fields (apiKey, baseURL, fetch, maxRetries, requestId) with their defaults. The agent will not invent timeout or region options that don’t exist.
• The exact method & type shapes. fm.send(SendOptions) returns SendResult; attachments are SendAttachment with Uint8Array auto-base64-encoded inside the SDK. The agent will pass typed fields to send, not hand-roll JSON literals or call the underlying REST surface.
• The retry policy. 5xx / 408 / 429 + network only — never 4xx, never a 401. The agent will not wrap fm.send in its own retry loop.
• The from-domain bound. from must land on the API key’s bound domain. The agent will not guess or invent a from address — it will ask the user.

What stays manual

The agent can’t mint an API key for you — the key is bound to one of your domains, and the SDK backend enforces that. Mint the key first, then point the agent at the skill.

1. Go to Settings → API Keys in the Flowmails dashboard.
2. Click Create key, name it, pick the domain the integration will send from.
3. Copy the raw fm_… key (shown exactly once) into your environment as FLOWMAILS_API_KEY.
4. Now run the agent prompt — it will install the skill, read the env var, wire up the client, and you’re done.

Versioning

The skill tracks @flowmails/flowmails-sdk v0.1. The SDK is currently private to Flowmails. The wire surface and class hierarchy are stable within the v0.1.x line; breaking changes will ship as v0.2.0. The skill install line (npx skills add wms-why/flowmails-sdk-plugin@flowmails-sdk) is the user-facing surface — keep it in sync with the mirrorwms-why/flowmails-sdk-plugin repo slug.

The update contract is enforced: any change to the public SDK surface ships a matching skill update in the same release. Run npx skills update to pull the latest; the version in the badge above updates when you do.