Sstekpad
API

Stekpad API

Programmatic access to mailbox management, warm-up control, health scores, DNS monitoring, and blacklist checking. Available on Pro and Enterprise plans.

Quick Start

Create an API key from Settings → API Keys and make your first request.

curl https://stekpad.com/api/v1/mailboxes \
  -H "Authorization: Bearer sk_live_your_api_key"

Authentication

Include your API key as a Bearer token in the Authorization header. All API keys start with sk_live_. Keys are hashed with SHA-256 before storage — we never store your raw key.

Authorization: Bearer sk_live_abc123def456...

Permissions

Each API key has read and/or write permissions. GET endpoints require read, POST/DELETE require write.

Plan requirement

API access is available on Pro (100 req/min) and Enterprise (500 req/min) plans only. Free plan users get a 403 error.

Base URL

https://stekpad.com/api

Health

System health check (no authentication required).

GET
/v1/health
Check if the API is operational.

Response

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-23T12:00:00.000Z"
}

Mailboxes

Create, list, and manage your connected email mailboxes.

GET
/v1/mailboxes
Auth required
List all mailboxes for the authenticated user.

Response

{
  "mailboxes": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "hello@acme.com",
      "provider": "gmail",
      "status": "active",
      "health_score": 91.5,
      "daily_limit": 25,
      "warmup_day": 14,
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ]
}
POST
/v1/mailboxes
Auth required
Add a new mailbox with SMTP/IMAP credentials.

Request body

{
  "email": "hello@acme.com",
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587,
  "smtp_user": "hello@acme.com",
  "smtp_pass": "your-app-password",
  "imap_host": "imap.gmail.com",
  "imap_port": 993,
  "imap_user": "hello@acme.com",
  "imap_pass": "your-app-password"
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "hello@acme.com",
  "status": "active",
  "message": "Mailbox created. Warm-up will start automatically."
}
GET
/v1/mailboxes/:id
Auth required
Get detailed information for a specific mailbox.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "hello@acme.com",
  "provider": "gmail",
  "status": "active",
  "health_score": 91.5,
  "daily_limit": 25,
  "warmup_day": 14,
  "warmup_started_at": "2026-03-01T10:00:00.000Z",
  "dns_status": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },
  "connection_error": null
}

Warm-up

Control warm-up status, pause/resume, and update configuration.

GET
/v1/warmup?mailbox_id=:id
Auth required
Get warm-up status, configuration, and recent email activity for a mailbox.

Response

{
  "mailbox_id": "550e8400-...",
  "email": "hello@acme.com",
  "status": "active",
  "health_score": 91.5,
  "daily_limit": 25,
  "warmup_day": 14,
  "warmup_mode": "balanced",
  "config": {
    "target_daily_limit": 40,
    "reply_rate": 30,
    "thread_rate": 15,
    "weekdays_only": false,
    "send_window_start": 8,
    "send_window_end": 18
  },
  "recent_emails": [
    {
      "id": "...",
      "status": "sent",
      "landed_in": "inbox",
      "subject": "Re: Q2 marketing strategy",
      "scheduled_at": "2026-03-23T10:30:00.000Z",
      "sent_at": "2026-03-23T10:32:15.000Z",
      "bounce_type": null,
      "bounce_category": null
    }
  ]
}
POST
/v1/warmup
Auth required
Pause, resume, or update warm-up configuration.

Request body

// Pause warm-up
{ "mailbox_id": "550e8400-...", "action": "pause" }

// Resume warm-up
{ "mailbox_id": "550e8400-...", "action": "resume" }

// Update configuration
{
  "mailbox_id": "550e8400-...",
  "action": "update_config",
  "config": {
    "warmup_mode": "aggressive",
    "target_daily_limit": 60,
    "reply_rate": 25,
    "send_window_start": 9,
    "send_window_end": 17
  }
}

Response

{
  "success": true,
  "message": "Configuration updated",
  "config": { ... }
}

Stats

Retrieve daily statistics and performance metrics.

GET
/v1/stats?mailbox_id=:id&days=7
Auth required
Get daily stats for a mailbox over a specified period.

Parameters: mailbox_id (required), days (optional, default 7, max 90)

Response

{
  "mailbox_id": "550e8400-...",
  "period": "7d",
  "stats": [
    {
      "date": "2026-03-23",
      "sent": 25,
      "delivered": 24,
      "opened": 18,
      "replied": 8,
      "bounced": 1,
      "spam_landed": 0,
      "inbox_rate": "96.00",
      "bounce_rate": "4.00",
      "reply_rate": "32.00",
      "health_score": "91.50"
    }
  ]
}

DNS

Check email authentication records (SPF, DKIM, DMARC).

GET
/v1/dns?mailbox_id=:id
Auth required
Get DNS authentication status. Add ?refresh=true for a live check.

Parameters: mailbox_id (required), refresh (optional, boolean)

Response

{
  "mailbox_id": "550e8400-...",
  "domain": "acme.com",
  "checked_at": "2026-03-23T12:00:00.000Z",
  "source": "cached",
  "spf": { "status": "pass", "record": "v=spf1 include:_spf.google.com ~all" },
  "dkim": { "status": "pass", "record": null },
  "dmarc": { "status": "pass", "record": "v=DMARC1; p=quarantine; rua=mailto:..." }
}

Blacklist

Check if your sending IP is listed on DNS blacklists.

GET
/v1/blacklist?mailbox_id=:id
Auth required
Get blacklist status. Add ?refresh=true for a live scan of 12 DNSBL.

Parameters: mailbox_id (required), refresh (optional, boolean)

Response

{
  "mailbox_id": "550e8400-...",
  "domain": "acme.com",
  "ip": "198.51.100.42",
  "checked_at": "2026-03-23T12:00:00.000Z",
  "listed": false,
  "blacklists_found": [],
  "total_checked": 8
}

Error Codes

All errors return a JSON object with an error field.

CodeDescription
400Bad Request — invalid parameters or request body.
401Unauthorized — missing or invalid API key.
403Forbidden — API requires Pro or Enterprise plan, or API key lacks required permission.
404Not Found — the requested resource does not exist or does not belong to your account.
429Rate Limited — too many requests. Check Retry-After header.
500Internal Server Error — something went wrong on our end.

Rate Limits

Pro

100

requests / minute

Enterprise

500

requests / minute

Rate limit info is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After (on 429).

Warm-up Modes

Set via the warm-up config endpoint. Each mode has different ramp-up behavior.

ModeStartMax/dayBounce limitUse case
slow2/day20/day0.5%New domains, first-time warm-up
balanced5/day40/day1%Default — most users
aggressive10/day80/day2%Established senders
recovery1/day15/day0.3%Damaged reputation

Ready to integrate?

Create your API key and start building with Stekpad.

    API Documentation — Stekpad