# Norbelys

> Cold email from your own inboxes: personal emails, follow-ups that stop the moment someone replies, and every reply in one inbox. One plan from $20 a month, AI included. The source is Apache-2.0.

Everything about people, campaigns, messages, replies, sending and webhooks is a public API operation. One OpenAPI contract (99 operations) generates the TypeScript and Python SDKs, the CLI's commands, the MCP server's tools and the API reference.

## Build on Norbelys

- [Developers](https://norbelys.com/developers): how one email travels through Norbelys, the first request, webhooks, MCP, the CLI and self-hosting.
- [OpenAPI contract](https://api.norbelys.com/openapi.json): the whole public API, served without a key. Base URL https://api.norbelys.com, versioned under /v1.
- [API reference](https://docs.norbelys.com/reference): every operation, with examples in cURL, JavaScript and Python.
- TypeScript SDK: `npm i @norbelys/sdk`, then `new Norbelys()` reads `NORBELYS_API_KEY`.
- Python SDK: `pip install norbelys`, then `Norbelys()` reads `NORBELYS_API_KEY`.
- MCP server: https://mcp.norbelys.com/mcp, over streamable HTTP with OAuth 2.1 and PKCE. Its 98 tools are named after the API's operations, such as messages.create and inbound_messages.list, and an assistant sees only the tools its grant allows.
- CLI: `curl --proto '=https' --tlsv1.2 -LsSf https://cli.norbelys.com/install.sh | sh` on macOS and Linux, then `norbelys login`. Every operation is a command; `norbelys listen --forward-to <url>` forwards your workspace's events to a local server.
- [Source and self-hosting](https://github.com/eusoumaxi/norbelys): `bun run selfhost:setup`, `bun run selfhost:migrate`, then `bun run selfhost:start`.

## Rules the API keeps

- Authenticate with `Authorization: Bearer <key>`. A key belongs to one workspace; a test key belongs to a test workspace, whose email never reaches a real inbox. There, a recipient whose address starts with bounce, blocked, defer, throttle or uncertain simulates that outcome.
- Every POST that changes something takes an `Idempotency-Key`. The same key within 24 hours replays the first answer (`Idempotent-Replayed: true`) instead of sending a second email. The SDKs generate one for every write.
- Updates take the version you read as `If-Match: "<version>"`; a stale one gets `412 precondition_failed`.
- Errors are RFC 9457 `application/problem+json` with a stable `code` and a `request_id`.
- Lists take `limit` (up to 100) and `cursor`. The SDKs walk every page.
- 6,000 requests a minute per workspace, reported in `RateLimit` headers, with `Retry-After` on a 429.

## Webhooks

- Signed the Standard Webhooks way: `webhook-id`, `webhook-timestamp`, `webhook-signature`. Verify with `verifyWebhook` from `@norbelys/sdk`.
- Ten attempts over about three days (now, then 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h, 24 h), 15 seconds each. Answering 410 switches the endpoint off.
- Events: message.queued, message.sent, message.failed, message.uncertain, message.cancelled, message.snippets_fallback, delivery_event.recorded, inbound_message.received, enrollment.stopped, enrollment.completed, campaign.status_changed, connection.health_changed, import.completed, export.completed, suppression.created, ai.budget_warning, ai.budget_exceeded, endpoint.test, webhook_endpoint.disabled.

## Product

- [Campaigns](https://norbelys.com/campaigns): multi-step sequences sent from your own inboxes on a schedule, stopped when someone replies.
- [AI personalization](https://norbelys.com/ai-personalization): a first line for each person from facts Norbelys finds, and replies sorted for you.
- [Pricing](https://norbelys.com/#pricing): one plan from $20 a month with every feature included.
- [Sign in or start](https://app.norbelys.com/sign-in)
- [Documentation](https://docs.norbelys.com)

## Optional

- [Meet Norbelys: cold email that gets replies, from $20 a month](https://norbelys.com/blog/introducing-norbelys/): Send from your own inboxes, follow up on autopilot and work every reply in one place. AI, warm-up and the unified inbox are all in the plan.
- [How to write a first line that doesn’t sound like a template](https://norbelys.com/blog/cold-email-first-lines/): Your first line decides whether the rest gets read. Five rules for openers that sound like a person wrote them, with before-and-after examples.
- [Follow-ups that get replies (and know when to stop)](https://norbelys.com/blog/follow-up-emails/): A lot of replies come from follow-ups, not the first email. Here’s a simple cadence, what to say in each touch and when to call it.
- [The cold email deliverability checklist, in plain English](https://norbelys.com/blog/cold-email-deliverability-checklist/): SPF, DKIM, DMARC, warm-up, daily limits and list hygiene, explained without the jargon. Run through it before your next campaign.