Quickstart

From a fresh terminal to your first contact upserted into SendGrid, Mailchimp, or Klaviyo in under five minutes — assuming the prerequisites below.

Before you start

• Node 22+ and npm installed (node -v, npm -v).
• A provider key for SendGrid, Mailchimp, or Klaviyo. See provider coverage for provider-specific notes.
• About 5 minutes.

Step 1 — Install the CLI

npm install -g @vorlek/cli
vorlek --version

If your environment blocks global npm installs, run the CLI in a temporary project with npm install @vorlek/cli and npx vorlek --version.

Step 2 — Sign up

vorlek auth signup

Interactive prompts ask for an email and a password (≥ 8 chars). You get back two API keys:

• vk_live_… — saved automatically to ~/.vorlek/config.json (mode 0600).
• vk_test_… — printed once and never shown again. Save it manually if you want deterministic test responses without calling a provider.

Already have an API key?

If you received a Vorlek API key for a smoke test, CI probe, or shared workspace, use it directly instead of signing up:

vorlek auth use --api-key "$VORLEK_API_KEY" --api-base https://api.vorlek.com
vorlek status

Keep API keys out of transcripts, shell history, and shared logs. Redact the key value if you need to attach command output.

Test mode

Use the one-time vk_test_… key from signup in CI, agent evals, and retry-path tests. Vorlek still runs auth, idempotency, validation, quota, rate-limit, and circuit-breaker middleware, but adapter HTTP calls are replaced by deterministic fixtures and every SDK result carries meta.test_mode: true.

Example CI probe for an agent retry path:

curl -X POST https://api.vorlek.com/v1/tools/upsert_contact \
  -H "Authorization: Bearer vk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 01HV8K5K7JJZ7JWQ9X0F7G8Q3A" \
  -H "X-Vorlek-Test-Outcome: rate_limited" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "sendgrid",
    "email": "retry-path@example.com"
  }'

The response is a normal error envelope with meta.test_mode: true and a Retry-After header, so the same retry handler can run in test and live mode.

Step 3 — Connect a provider

vorlek connect sendgrid --api-key SG.your_sendgrid_key_here
# or
vorlek connect mailchimp --api-key your_key-us7 --list-id a1b2c3d4e5
# or
vorlek connect klaviyo --api-key pk_your_klaviyo_private_key

Vorlek validates the key against the provider, encrypts it with AES-256-GCM, and stores the ciphertext server-side. If the key is wrong or lacks scope, you get a clear error before anything is stored.

Step 4 — Upsert your first contact

vorlek contact upsert \
  --email jamie@example.com \
  --first-name Jamie \
  --properties '{"plan":"free","loyalty_tier":"gold"}'

Behind the scenes:

1. Vorlek normalizes the input + dispatches to the SendGrid adapter.
2. For each property the adapter doesn't know yet (plan, loyalty_tier), it auto-creates the field at SendGrid and records the mapping.
3. It calls PUT /v3/marketing/contacts and returns the unified envelope.

Successful output:

contact_id        f1ec8680-...
action            upserted
fields_auto_created   plan, loyalty_tier
provider          sendgrid
quota             1 / 1000 (resets 2026-05-01)

Step 5 — Verify in SendGrid

Open mc.sendgrid.com/contacts and search for jamie@example.com. You should see the contact with plan and loyalty_tier populated. If the new fields don't appear in the contact yet, give it 1–2 minutes — SendGrid takes a moment to index newly-created custom fields.

What's next

• Full upsert_contact reference — every field, every error path
• get_connection_status reference — live provider validation
• send_transactional reference — synchronous transactional sends
• get_campaign_stats reference — normalized campaign metrics
• Python SDK — install vorlek and call the API from Python 3.10+
• TypeScript SDK — install @vorlek/sdk and call the API with generated types
• MCP Server — configure @vorlek/email-mcp in Claude Desktop, Cline, or Cursor
• Provider coverage — what is supported for SendGrid, Mailchimp, and Klaviyo
• Test mode — deterministic outcomes for retry paths, CI, and agent evals
• Error codes — what each one means and how to recover
• SKILL.md — the canonical machine-readable spec for agents

Direct API call (no CLI)

If you'd rather skip the CLI and call the REST API yourself:

curl -X POST https://api.vorlek.com/v1/tools/upsert_contact \
  -H "Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jamie@example.com",
    "first_name": "Jamie",
    "properties": {"plan": "free", "loyalty_tier": "gold"}
  }'

You get a Vorlek key the same way — POST https://api.vorlek.com/v1/accounts/signup with {"email": "...", "password": "≥12 chars"} returns the live + test keys.