How to Embed Email Infrastructure in Your App with the Winnr API

Every SaaS product that touches outbound email eventually hits the same wall: where do the mailboxes come from?

If you're building an AI SDR tool, your AI agent needs real email accounts to send from. If you're building a sequencer, your users need dozens of warmed inboxes to run campaigns. If you're running an agency, you need to spin up mailboxes for every new client -- fast, reliably, and without manually clicking through a hosting control panel.

The traditional approach is painful. You either ask users to BYO their own Google Workspace or Microsoft 365 accounts (creating onboarding friction, support headaches, and suspension risk), or you build and maintain your own SMTP infrastructure (which is an entire engineering team's worth of work). Neither option scales.

There's a third path: use an API to provision fully managed email infrastructure on demand. That's what Winnr's API is built for. You make API calls, and production-ready mailboxes with proper DKIM, SPF, and DMARC authentication appear in seconds. Your users never know or care that Winnr exists behind the scenes -- they just see that email works inside your product.

This guide walks through the complete integration from first API call to sending production email, with code examples you can copy and adapt.

Why Embed Email Infrastructure?

Before diving into the technical walkthrough, let's be clear about why building email infrastructure into your product matters -- and why asking users to bring their own accounts is increasingly untenable.

Google and Microsoft are hostile to cold outreach. Google Workspace suspends accounts that send more than ~50 cold emails per day. Microsoft 365 is even stricter since their March 2026 changes. If your product's value proposition depends on sending outbound email at scale, building on top of consumer email providers puts a hard ceiling on what your users can do -- and puts your support team on the hook every time an account gets suspended. (Read our SMTP vs Google/Microsoft comparison for the full breakdown.)

Onboarding friction kills conversion. Asking a new user to go set up Google Workspace, buy domains, configure DNS records, connect IMAP credentials, and then come back to your app is a multi-step, multi-day process. Most users drop off before they send a single email. When you provision infrastructure via API, the user signs up, and mailboxes are ready within minutes. That's the difference between a 10% activation rate and a 60% activation rate.

You capture more revenue. If your users are paying Google $7/user/month for Workspace accounts you don't control, that's revenue you're not capturing. When you embed infrastructure, you can bundle mailbox costs into your platform pricing -- either as an included feature or as a transparent line item. Either way, your unit economics improve because you're providing more of the value stack.

You control the quality. With BYO accounts, you have zero control over DNS configuration, sending reputation, IP quality, or warmup status. When you provision infrastructure via API, every mailbox comes with verified SPF, DKIM, and DMARC, clean dedicated IPs, and proper warmup -- because you configured it that way. Deliverability goes up, support tickets go down.

Use Cases: Who Needs This

The Winnr API is used by a wide range of products. Here are the most common patterns we see:

AI SDR Platforms

AI-powered sales development reps are the fastest-growing category of products integrating email infrastructure. An AI SDR agent needs to send personalized outbound emails, monitor replies, respond intelligently, and book meetings -- all autonomously. That means it needs real mailboxes that it controls end to end.

The typical integration pattern: when a user configures their AI agent, your platform calls the Winnr API to provision 5-20 mailboxes across 2-4 domains. The agent sends through these mailboxes on rotation, reads replies via the inbox API, and handles conversations. When a domain's reputation dips, the agent automatically provisions replacement infrastructure. No human intervention required.

Cold Email Sequencer Platforms

Sequencer platforms like Instantly, Smartlead, and Lemlist all face the same infrastructure gap: their software orchestrates email sequences, but the actual sending infrastructure comes from the user. This creates a fragile dependency on Google Workspace and Microsoft 365 accounts that regularly get suspended, throttled, or banned.

By embedding Winnr's infrastructure, a sequencer platform can offer turnkey email accounts as part of the subscription. Users activate a campaign and the platform automatically provisions warmed mailboxes, connects domains, and starts sending -- without the user ever touching a DNS record or a Google admin panel. This eliminates the #1 support issue for every sequencer platform: "my Google account got suspended."

CRMs with Built-In Outreach

Modern CRMs are increasingly adding outbound email features. HubSpot, Salesforce, and dozens of vertical CRMs now offer email sequences alongside their core contact management. But most of them rely on the user connecting their existing email account via OAuth -- which means they inherit all of that account's limitations.

A CRM that provisions dedicated outreach infrastructure via API offers a fundamentally better experience: higher sending limits, better deliverability (because the accounts are purpose-built for outreach, not shared with the user's personal inbox), and zero risk of the user's primary email getting suspended because of outreach activity.

Agency Management Platforms

Lead generation agencies manage outreach for dozens or hundreds of clients simultaneously. Each client needs their own domains, their own mailboxes, their own sending reputation. Manually provisioning this infrastructure through a dashboard is feasible for 5 clients but breaks down completely at 50.

The API integration pattern here is straightforward: when the agency onboards a new client, the platform calls the Winnr API to register domains, provision mailboxes, and start warmup automatically. The agency manages everything from their own dashboard -- and can optionally use Winnr's reseller features to whitelabel the infrastructure under their own brand.

Email Verification and Testing Tools

Products that test email deliverability, validate email addresses, or monitor inbox placement need real mailboxes to send from and receive into. The Winnr API lets these tools provision test infrastructure programmatically and tear it down when testing is complete, without maintaining permanent infrastructure for ephemeral use cases.

Internal Tools and Automation

Not every integration is a SaaS product. We see engineering teams use the API to build internal tools: automated new-hire email provisioning, marketing campaign infrastructure, customer communication systems, and notification delivery. If your team needs to create and manage email accounts programmatically, the same API works whether you're building a product or an internal tool.

How the API Works: Architecture Overview

Before writing code, it helps to understand what happens behind the scenes when you make API calls. Winnr's infrastructure is fully managed -- you don't run any email servers -- but understanding the architecture helps you build a more robust integration.

Key architectural details:

• Async provisioning: Domain setup and mailbox creation are asynchronous operations. The API returns a job_id immediately, and provisioning happens in the background (typically 30-90 seconds). You poll the jobs endpoint for status.
• DNS management: Winnr manages DNS records (MX, SPF, DKIM, DMARC) automatically. You either point nameservers to Winnr's DNS, or provide a Cloudflare API token and Winnr writes the records directly into your Cloudflare zone.
• Dedicated infrastructure: Mailboxes run on dedicated SMTP servers with clean IP reputation -- not shared sending pools. Each account gets its own sending identity.
• Built-in warmup: New mailboxes automatically enter Winnr's warmup program, which builds sending reputation through real engagement signals over 14-21 days.

The full API reference documents every endpoint, request/response schema, and error code. What follows is the practical, step-by-step integration path.

Step 1: Authentication & API Tokens

Every API call requires a Bearer token. You create tokens from the Winnr dashboard or via the API itself.

Create a token via the API

curl -X POST https://api.winnr.app/v1/auth/tokens \
  -H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App - Production",
    "permissions": ["read", "write"]
  }'

Response:

{
  "id": "tok_abc123",
  "name": "My App - Production",
  "token": "wnr_acct123_sk_live_...",
  "permissions": ["read", "write"],
  "created_at": "2026-03-22T10:00:00Z"
}

All subsequent API calls use this token:

curl https://api.winnr.app/v1/account \
  -H "Authorization: Bearer wnr_acct123_sk_live_..."

Python example

import requests

WINNR_API = "https://api.winnr.app/v1"
TOKEN = "wnr_acct123_sk_live_..."

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

# Verify your account
resp = requests.get(f"{WINNR_API}/account", headers=headers)
print(resp.json())
# {"id": "acct_123", "name": "My Agency", "plan": "growth", ...}

Step 2: Connect a Domain

Before creating mailboxes, you need at least one domain connected. Winnr supports two connection flows:

1. Nameserver delegation -- Winnr creates a DNS zone and gives you nameservers to set at your registrar. Winnr then manages all DNS records (MX, SPF, DKIM, DMARC) automatically.
2. Cloudflare integration -- You provide a Cloudflare API token and Winnr writes DNS records directly into your existing Cloudflare zone. No nameserver change required.

Option A: Nameserver delegation (recommended for new domains)

curl -X POST https://api.winnr.app/v1/domains/connect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["outreach-acme.com", "mail-acme.com"]
  }'

Response:

{
  "domains": [
    {
      "id": "dom_abc",
      "name": "outreach-acme.com",
      "status": "pending",
      "nameservers": ["ns1.winnr.app", "ns2.winnr.app"]
    },
    {
      "id": "dom_def",
      "name": "mail-acme.com",
      "status": "pending",
      "nameservers": ["ns1.winnr.app", "ns2.winnr.app"]
    }
  ]
}

At this point, you (or your user) need to update the domain's nameservers at the registrar to point to the Winnr nameservers. This is the one manual step in the flow -- unless you use the Cloudflare integration.

Option B: Cloudflare integration (zero manual DNS steps)

curl -X POST https://api.winnr.app/v1/domains/connect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["outreach-acme.com"],
    "cloudflare_api_token": "cf_token_..."
  }'

When you provide a cloudflare_api_token, Winnr creates MX, SPF, DKIM, and DMARC records directly in your Cloudflare zone. No nameserver change. No manual steps. This is the fastest path to production if your domains are already on Cloudflare.

Bulk domain search (optional)

If you want to help users find available domains, use the search endpoints:

# Check availability of up to 100 domains at once
curl -X POST https://api.winnr.app/v1/domains/search-bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["acme-outreach.com", "acme-mail.com", "acme-sales.com"]
  }'

# Or get AI-generated domain suggestions
curl https://api.winnr.app/v1/domains/suggest?keyword=acme \
  -H "Authorization: Bearer $TOKEN"

Step 3: Verify DNS & Provision

After connecting domains and updating nameservers (or using Cloudflare), verify the DNS configuration:

curl -X POST https://api.winnr.app/v1/domains/check-ns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "outreach-acme.com"}'

Response when verified:

{
  "verified": true,
  "nameservers": ["ns1.winnr.app", "ns2.winnr.app"],
  "message": "Nameservers verified. Domain queued for provisioning."
}

When verified is true, Winnr automatically queues the domain for full provisioning -- MX records, DKIM key generation, SPF/DMARC policies, and mail server configuration. You can also explicitly trigger setup:

curl -X POST https://api.winnr.app/v1/domains/setup \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "outreach-acme.com"}'

# Returns: {"job_id": "job_xyz", "status": "pending"}

Check DNS propagation status at any time:

curl https://api.winnr.app/v1/domains/dom_abc/dns-status \
  -H "Authorization: Bearer $TOKEN"

# Returns verification status for NS, MX, SPF, DKIM records

Step 4: Create Mailboxes

Once a domain is provisioned, you can create mailboxes. This is where most integrations get exciting -- a single API call creates production-ready email accounts with full IMAP/SMTP access.

Single mailbox

curl -X POST https://api.winnr.app/v1/email-users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "sarah",
    "domain": "outreach-acme.com",
    "name": "Sarah Chen"
  }'

Response:

{
  "job_id": "job_m1",
  "status": "pending",
  "email": "sarah@outreach-acme.com",
  "username": "sarah"
}

Bulk mailbox creation (up to 500 at once)

This is the endpoint most integrations rely on. Create all of a user's mailboxes in one call:

curl -X POST https://api.winnr.app/v1/email-users/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "outreach-acme.com",
    "users": [
      {"username": "sarah", "name": "Sarah Chen"},
      {"username": "james", "name": "James Rivera"},
      {"username": "alex", "name": "Alex Kim"},
      {"username": "maria", "name": "Maria Santos"},
      {"username": "david", "name": "David Park"}
    ]
  }'

Response:

{
  "job_id": "job_bulk_01",
  "users_count": 5,
  "status": "pending"
}

Python: Full provisioning workflow

Here's a complete Python example that connects a domain, waits for provisioning, and creates mailboxes:

import requests
import time

API = "https://api.winnr.app/v1"
HEADERS = {
    "Authorization": "Bearer wnr_acct123_sk_live_...",
    "Content-Type": "application/json",
}

def wait_for_job(job_id, timeout=300):
    """Poll job status until completed or failed."""
    start = time.time()
    while time.time() - start < timeout:
        resp = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS)
        job = resp.json()
        if job["status"] == "completed":
            return job
        if job["status"] == "failed":
            raise Exception(f"Job failed: {job.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"Job {job_id} timed out")

# 1. Connect the domain
resp = requests.post(f"{API}/domains/connect", headers=HEADERS, json={
    "domains": ["outreach-acme.com"]
})
domain = resp.json()["domains"][0]
print(f"Domain {domain['name']} connected. Set NS to: {domain['nameservers']}")

# 2. Wait for DNS verification (after NS change at registrar)
#    In production, you'd poll this on a schedule or webhook
verified = False
while not verified:
    resp = requests.post(f"{API}/domains/check-ns", headers=HEADERS, json={
        "domain": "outreach-acme.com"
    })
    verified = resp.json().get("verified", False)
    if not verified:
        print("Waiting for DNS propagation...")
        time.sleep(60)

# 3. Create mailboxes in bulk
resp = requests.post(f"{API}/email-users/bulk", headers=HEADERS, json={
    "domain": "outreach-acme.com",
    "users": [
        {"username": "sarah", "name": "Sarah Chen"},
        {"username": "james", "name": "James Rivera"},
        {"username": "alex", "name": "Alex Kim"},
        {"username": "maria", "name": "Maria Santos"},
        {"username": "david", "name": "David Park"},
    ]
})
job = wait_for_job(resp.json()["job_id"])
print(f"Created {len(job.get('users', []))} mailboxes!")

# 4. List all mailboxes to verify
resp = requests.get(f"{API}/email-users", headers=HEADERS, params={
    "domain": "outreach-acme.com"
})
for user in resp.json()["users"]:
    print(f"  {user['email']} - {user['status']}")

Generate usernames with AI

If you want realistic-looking mailbox names without hardcoding them, use the name generation endpoint:

curl -X POST https://api.winnr.app/v1/email-users/generate-names \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"count": 5, "style": "professional"}'

# Returns: ["sarah.chen", "james.r", "m.santos", "d.park", "alex.kim"]

Step 5: Send Email

Once mailboxes are provisioned, you can send email through them via the API. Each mailbox has its own sending identity and reputation.

curl -X POST https://api.winnr.app/v1/email-users/usr_abc/inbox/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "prospect@company.com",
    "subject": "Quick question about your Q2 roadmap",
    "body": "<p>Hi Jordan,</p><p>I noticed your team just launched...</p>",
    "html": true
  }'

Response:

{
  "message_id": "<abc123@outreach-acme.com>",
  "status": "sent"
}

Threading: Reply to conversations

For AI SDR tools and sequencers that need to reply in-thread, use the in_reply_to and references fields:

curl -X POST https://api.winnr.app/v1/email-users/usr_abc/inbox/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "prospect@company.com",
    "subject": "Re: Quick question about your Q2 roadmap",
    "body": "<p>Thanks for the reply, Jordan! That makes sense...</p>",
    "html": true,
    "in_reply_to": "<reply-xyz@company.com>",
    "references": "<abc123@outreach-acme.com> <reply-xyz@company.com>"
  }'

This ensures the reply appears in the same email thread in the recipient's inbox -- critical for engagement rates and natural-looking AI conversations.

Step 6: Read the Inbox

For AI agents and sequencers, reading replies is just as important as sending. The inbox API gives you full access to each mailbox's incoming messages.

# List inbox messages
curl https://api.winnr.app/v1/email-users/usr_abc/inbox \
  -H "Authorization: Bearer $TOKEN"

# Get full message body
curl https://api.winnr.app/v1/inbox/msg_123/body \
  -H "Authorization: Bearer $TOKEN"

# List attachments
curl https://api.winnr.app/v1/inbox/msg_123/attachments \
  -H "Authorization: Bearer $TOKEN"

# Download a specific attachment (returns presigned S3 URL)
curl https://api.winnr.app/v1/inbox/msg_123/attachments/0 \
  -H "Authorization: Bearer $TOKEN"

Python: AI agent reply loop

def check_and_reply(user_id):
    """Check inbox for new replies and process them."""
    resp = requests.get(
        f"{API}/email-users/{user_id}/inbox",
        headers=HEADERS
    )
    messages = resp.json().get("messages", [])

    for msg in messages:
        if msg.get("is_read"):
            continue

        # Get the full message body
        body_resp = requests.get(
            f"{API}/inbox/{msg['uid']}/body",
            headers=HEADERS
        )
        body = body_resp.json().get("body", "")

        # Your AI processes the reply here
        ai_response = generate_ai_reply(body)

        # Send the reply in-thread
        requests.post(
            f"{API}/email-users/{user_id}/inbox/send",
            headers=HEADERS,
            json={
                "to": msg["from"],
                "subject": f"Re: {msg['subject']}",
                "body": ai_response,
                "html": True,
                "in_reply_to": msg.get("message_id"),
                "references": msg.get("references", ""),
            }
        )

Monitoring Async Jobs

Domain provisioning and mailbox creation are asynchronous. Every async operation returns a job_id that you can poll for status:

curl https://api.winnr.app/v1/jobs/job_xyz \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "job_xyz",
  "type": "domain_setup",
  "status": "completed",
  "progress": 100,
  "message": "Domain outreach-acme.com provisioned successfully",
  "resource_id": "dom_abc",
  "created_at": "2026-03-22T10:00:00Z",
  "completed_at": "2026-03-22T10:01:15Z"
}

Job statuses: pending → processing → completed or failed. Typical provisioning times:

For production integrations, we recommend polling every 5 seconds for the first 30 seconds, then every 15 seconds after that. Or list all recent jobs to get a batch view:

curl "https://api.winnr.app/v1/jobs?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Going Deeper: Reseller & Whitelabel

If you want to offer email infrastructure as a branded feature of your platform -- not just use it behind the scenes -- Winnr's reseller API gives you full multi-tenant capabilities.

What the reseller API adds

Create a sub-account for each customer

curl -X POST https://api.winnr.app/v1/reseller/accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@acmecorp.com",
    "first_name": "Jordan",
    "last_name": "Lee",
    "company_name": "Acme Corp",
    "domain_limit": 10,
    "email_user_limit": 50
  }'

Response:

{
  "account_id": "acct_sub_456",
  "email": "client@acmecorp.com",
  "password_reset_link": "https://app.winnr.app/reset?token=..."
}

Each sub-account is fully isolated: its own domains, its own mailboxes, its own usage limits. You can manage all sub-accounts from your parent account, or let customers log into the Winnr dashboard themselves (optionally whitelabeled under your brand).

Whitelabel: Your brand, Winnr's infrastructure

# Set your brand
curl -X PATCH https://api.winnr.app/v1/reseller/profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "AcmeMail",
    "primary_color": "#4F46E5",
    "support_email": "support@acmemail.com"
  }'

# Set your custom domain
curl -X POST https://api.winnr.app/v1/reseller/domain \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.acmemail.com"}'

# Returns DNS instructions (CNAME record) for verification

Once configured, your customers see your brand name, your colors, and your domain when they log in. They never see "Winnr" anywhere.

Integration Best Practices

After working with dozens of teams that have integrated the Winnr API into their products, here are the patterns that lead to the most reliable and scalable integrations:

1. Poll jobs, don't assume instant completion. Mailbox creation is async. Always poll /v1/jobs/{id} before treating a mailbox as ready. Most provisioning completes in under 90 seconds, but assuming instant completion is the #1 source of integration bugs. Build a job status page or progress indicator in your UI.

2. Respect warmup before sending cold email. A freshly provisioned mailbox has zero sending reputation. If your product sends cold email, don't start campaigns the day mailboxes are created. Wait for Winnr's built-in warmup to build reputation over 14-21 days first. Sending cold email from brand-new, un-warmed accounts is the fastest way to land in spam. (See our warmup guide for details.)

3. Use bulk endpoints for efficiency. Creating 50 mailboxes one at a time means 50 API calls and 50 jobs to track. Creating them with /v1/email-users/bulk means 1 API call and 1 job. The bulk endpoint accepts up to 500 users per request.

4. Handle rate limits gracefully. The API enforces per-account limits on domains and email users. Check GET /v1/account/usage before provisioning to avoid 403 errors. Display remaining capacity in your UI so users understand their limits.

5. Build for domain rotation. For cold email use cases, plan for domain rotation from the start. Domains accumulate sending reputation (both positive and negative). The best integrations provision multiple domains per user and rotate sending across them. When a domain's reputation dips, the system automatically provisions a replacement.

6. Use the Cloudflare flow for zero-touch onboarding. If your users manage DNS through Cloudflare, the cloudflare_api_token parameter on /v1/domains/connect eliminates the manual nameserver step entirely. This is the difference between "set up takes 30 seconds" and "set up takes 24 hours (DNS propagation)."

7. Store Winnr IDs in your database. Map your internal user/account/campaign objects to Winnr domain_ids and user_ids. This makes it trivial to send through specific mailboxes, check their status, or delete them when a customer churns.