Quick answer

The Winnr API at https://api.winnr.app/v1 covers Account, Domains (search, purchase, connect, DNS status, custom DNS records, DMARC, redirects and forwarding), Email Users, Warming, Inbox, Export, Jobs, the Pre-warmed marketplace, Webhooks and Message lookup, plus API tokens, team users and templates. It uses standard REST verbs and JSON. Operations that take time (buying or connecting domains, creating mailboxes) return a job ID you can poll. The full OpenAPI spec with an interactive explorer is at app.winnr.app/docs.

Resources

All paths below are relative to https://api.winnr.app.

Account - GET /v1/account and GET /v1/account/usage: plan, limits, usage (domains, email users, pre-warmed addresses) and the calling token's permissions. - POST /v1/account/email-credits: set how many extra email user credits ($1/mailbox/month) you pay for. - POST /v1/account/universal-inbox with {"enabled": true|false}: turn inbox syncing (the universal inbox) on or off. Turning it off returns 409 while an enabled webhook subscribes to email.received.

Domains - GET /v1/domains/search, POST /v1/domains/search-bulk: check availability and price. - POST /v1/domains/purchase: buy domains. Returns a job per domain. Each domain entry can carry an optional forward_address (and redirect_url), applied once the domain is set up. - POST /v1/domains/connect, POST /v1/domains/check-provider, POST /v1/domains/check-ns: connect domains you already own. - POST /v1/domains/convert-subdomain-strategy: add Subdomain Strategy subdomains under a domain you already have. - GET /v1/domains, GET /v1/domains/{domain_id}, PATCH /v1/domains/{domain_id} (tags, redirect URL, forwarding address), DELETE /v1/domains/{domain_id}, POST /v1/domains/bulk-delete. - GET /v1/domains/{domain_id}/email-users: mailboxes on a domain, with connection details. - DNS: GET /v1/domains/{domain_id}/dns-status, GET /v1/domains/{domain_id}/dns-records (the records to add yourself when you manage DNS), POST /v1/domains/{domain_id}/verify-dns, POST /v1/domains/recheck-dns-health. - Custom DNS records: GET and POST /v1/domains/{domain_id}/custom-dns-records, PATCH and DELETE /v1/domains/{domain_id}/custom-dns-records/{record_id}. Add your own records (for example website or verification records) on domains whose DNS Winnr manages. See Custom DNS records. - DMARC: PUT /v1/domains/{domain_id}/dmarc sets your own DMARC value, DELETE restores Winnr's default. - Redirects and forwarding: POST and DELETE /v1/domains/{domain_id}/redirect (send website visitors to another URL), POST and DELETE /v1/domains/{domain_id}/forward (copy incoming mail to another address).

Email Users - GET /v1/email-users (filter with filter[domain]), GET /v1/email-users/{user_id}. - POST /v1/email-users (one mailbox) and POST /v1/email-users/bulk (up to 100 on one domain). Both return a job. - PATCH /v1/email-users/{user_id} (display name, password), DELETE /v1/email-users/{user_id}, DELETE /v1/email-users/bulk. - POST /v1/email-users/replace: delete and recreate up to 100 mailboxes with new addresses. Destructive: requires acknowledge_data_loss: true and returns a job.

Warming - GET /v1/warming, GET /v1/warming/overview, GET /v1/warming/metrics, GET /v1/warming/{user_id}/metrics, GET /v1/warming/{user_id}/activity, POST /v1/warming/refresh. - POST /v1/warming/enable and POST /v1/warming/disable (plus -async versions for large batches). Enabling warming is billed at $0.60/mailbox/month. - POST /v1/warming/{user_id}/pause, POST /v1/warming/{user_id}/resume, PATCH /v1/warming/{user_id}/settings, and bulk versions (bulk-pause, bulk-resume, bulk-settings). - GET and PATCH /v1/warming/seed-phrase. - POST /v1/warming/import and DELETE /v1/warming/import/{user_id}: warm mailboxes hosted outside Winnr.

Inbox - Unified inbox across all mailboxes: GET /v1/inbox, POST /v1/inbox/refresh, GET /v1/inbox/{uid}/body, GET /v1/inbox/{uid}/attachments, PATCH /v1/inbox/{uid} (mark read), DELETE /v1/inbox/{message_id}, POST /v1/inbox/bulk-delete. - Per mailbox: GET /v1/email-users/{user_id}/inbox, POST /v1/email-users/{user_id}/inbox/send, POST /v1/email-users/{user_id}/inbox/refresh. - POST /v1/upload/presign: upload an attachment before sending.

Export - GET /v1/export/formats and POST /v1/export: credentials in the format your sending tool expects (Smartlead, Instantly, EmailBison, Reply.io, Woodpecker and many more). Limited to one export every 5 seconds, and requires write permission because the file contains passwords.

Jobs - GET /v1/jobs (filter with filter[status] and filter[type]) and GET /v1/jobs/{job_id}. Statuses are pending, in_progress, completed and failed.

Pre-warmed marketplace - GET /v1/prewarmed/browse, GET /v1/prewarmed/{domain_name}, POST /v1/prewarmed/{domain_name}/blocklist-check. - POST /v1/prewarmed/purchase (one domain) and POST /v1/prewarmed/purchase-batch (up to 25 domains, one charge). Both charge the first month immediately. - GET /v1/prewarmed/my-domains, POST /v1/prewarmed/cancel, POST /v1/prewarmed/auto-renew.

Webhooks and message lookup - POST /v1/webhooks, GET /v1/webhooks, GET, PATCH and DELETE /v1/webhooks/{webhook_id}. - GET /v1/webhooks/{webhook_id}/secret, POST /v1/webhooks/{webhook_id}/rotate-secret, POST /v1/webhooks/{webhook_id}/test. - GET /v1/webhooks/{webhook_id}/deliveries and POST /v1/webhooks/{webhook_id}/deliveries/{event_id}/redeliver. - GET /v1/messages/lookup: map your Message-ID to the one an upstream provider assigned, or back. - See Webhooks and message-id lookup.

API tokens, team and templates - GET and POST /v1/auth/tokens, DELETE /v1/auth/tokens/{token_id}. - GET /v1/account/users, POST /v1/account/users/invite, PATCH and DELETE /v1/account/users/{user_id}. - GET and POST /v1/email-user-templates, GET, PATCH and DELETE /v1/email-user-templates/{template_id}.

Common patterns

Buy a domain and wait for it:

  1. POST /v1/domains/search-bulk to check availability and price.
  2. POST /v1/domains/purchase with the domains you want. Each domain comes back with a job_id.
  3. GET /v1/jobs/{job_id} every 10-30 seconds until the status is completed (or subscribe to the domain.ready webhook).
  4. GET /v1/domains to fetch the provisioned domain.

Bulk-create mailboxes:

  1. POST /v1/email-users/bulk with the domain and up to 100 users. Returns a job.
  2. Poll GET /v1/jobs/{job_id} until it completes.
  3. GET /v1/email-users?filter[domain]=yourdomain.com to list them, or POST /v1/export to get credentials for your sending tool.

Rate limit awareness

Rate limits apply per account, across all your tokens:

Above the limit, Winnr returns 429 with a Retry-After header. See Rate limits.

What's next

Related articles

Frequently asked questions

Where's the full spec?

[app.winnr.app/docs](https://app.winnr.app/docs) has an interactive explorer with request and response schemas. You can also download the OpenAPI file from the API page in the app (Download OpenAPI Spec).

Do long-running operations block?

No. They return immediately with a job ID. Poll GET /v1/jobs/{job_id} until the status is completed or failed, or subscribe to webhook events such as domain.ready and email_user.created.

What does a response look like?

JSON. Successful responses carry the result in data plus a meta block with a request_id. Errors use standard HTTP status codes and an error object with a machine-readable code and a human-readable message.

How does pagination work?

List endpoints return up to 100 items per page (default 25) using limit and cursor query parameters.

Is there an official SDK?

No official SDK, but the OpenAPI spec generates typed clients for most languages. For AI assistants, use the Winnr MCP server instead.

Can read-only tokens call every GET endpoint?

Yes. Read-only tokens can call any GET endpoint and a few read-only lookups sent as POST (bulk domain search, DNS provider check and the pre-warmed blocklist check). Everything that creates, changes or deletes needs a token with write permission, and so does a credentials export.

Was this article helpful? Yes · No