Quickstart

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

Before you start

• Node 24+ and pnpm installed (node -v, pnpm -v). If you don't have pnpm, run corepack enable on Node 24+.
• A SendGrid Marketing API key with marketing.read + marketing.write scope. Get one at app.sendgrid.com/settings/api_keys → Create API Key → Restricted Access → tick the two Marketing scopes. Keys start with SG. and are shown once.
• About 5 minutes.

Step 1 — Install the CLI

git clone https://github.com/vorlek/vorlek-cli.git
cd vorlek-cli
pnpm install
pnpm build
pnpm link --global

vorlek --version

If pnpm link --global fails with a PNPM_HOME error, run pnpm setup first and follow its instructions to update your shell rc, then re-open the terminal.

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 to use test mode (validates inputs without calling the provider; doesn't count against quota).

Step 3 — Connect SendGrid

vorlek connect sendgrid --api-key SG.your_sendgrid_key_here

Vorlek validates the key against GET /v3/user/profile, 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
• 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.