API v1MailFor Developer Documentation & REST Reference

Built for developers who demand full control.

Everything in MailFor is accessible via REST APIs and real-time HMAC-signed webhooks. Manage sender mailboxes, automate multi-step campaigns, and stream deliverability events.

Quickstart GuideExplore REST Endpoints
  • Strict tenant isolation
  • HMAC SHA-256 Webhook signatures
  • RFC 5322 MIME compilation
01. Overview02. Authentication03. Quickstart04. Endpoints05. Webhooks06. Error Codes
01 · Architecture

Dual-Plane Engine Architecture

MailFor operates on a decoupled Control Plane (REST API, database state, sequence schedules, AI classification) and an Execution Plane (distributed sender workers).

Control Plane (API)

Accepts writes, validates recipient schemas, enforces idempotency, checks deliverability safety rules, and schedules dispatch jobs.

Execution Plane (Workers)

Connects directly to mailbox IMAP/SMTP nodes and OAuth endpoints, handles warmup exchanges, simulates human typing pauses, and streams event receipts.

02 · Security

Authentication & Scoped Keys

Authenticate all requests by passing your API key in the standard Authorization header. Each key carries granular permission scopes.

# Standard HTTP Request Header
Authorization: Bearer mfr_live_8f3kq29188a09b...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Scope NameCapabilityRecommended For
mailboxes:readList mailboxes, inspect warmup health, view send volume.Dashboards, analytics sync
mailboxes:writeConnect mailboxes, modify ramp schedule, quarantine.Automated provisioning
sequences:writeCreate, launch, pause, and edit multi-step campaigns.CRM & campaign triggers
contacts:writeUpload contacts, manage tags, update suppression list.Lead enrichment pipelines
crm:read / crm:writeRead replies, send thread responses, manage deal stages.Unified inbox integrations
03 · Quickstart

Interactive Code Examples

Fetch all active mailboxes and launch an automated campaign in under 10 lines of code.

POST /v1/campaigns
curl -X POST https://mailfor.tech/v1/campaigns \
  -H "Authorization: Bearer $MAILFOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Enterprise Outreach",
    "mailbox_ids": ["mbx_01HQX892"],
    "steps": [
      {
        "step_number": 1,
        "delay_days": 0,
        "subject": "Quick question on deliverability",
        "body": "Hi {{first_name}}, saw your team is expanding outbound..."
      }
    ]
  }'
04 · Reference

REST API Endpoints

Every endpoint accepts and returns JSON with standard HTTP status codes.

Mailboxes & Warmup

Connect, manage, ramp, and monitor sender mailboxes across Google, Microsoft, and SMTP/IMAP.

GET/v1/mailboxes
Scope: mailboxes:read
List Mailboxes

Retrieve all connected mailboxes in the current workspace with health scores and daily volume stats.

Parameters
status(string)
Filter by status: active, warming, quarantined, error
limit(integer)
Pagination limit (default: 50, max: 100)
200 OK Responseapplication/json
{
  "data": [
    {
      "id": "mbx_01HQX892",
      "email": "sarah@outreach.acme.com",
      "provider": "google_oauth",
      "status": "warming",
      "health_score": 98.5,
      "daily_limit": 45,
      "sent_today": 22,
      "warmup_enabled": true,
      "warmup_stats": {
        "sent_warmup": 18,
        "received_warmup": 16,
        "inbox_placement_rate": 0.99
      },
      "created_at": "2026-09-15T10:00:00Z"
    }
  ],
  "has_more": false
}
POST/v1/mailboxes
Scope: mailboxes:write
Connect Custom IMAP/SMTP Mailbox

Directly register a mailbox with custom IMAP and SMTP credentials for outreach & warmup.

Request Body (JSON)
{
  "email": "alex@outreach.acme.com",
  "name": "Alex Mercer",
  "smtp": {
    "host": "smtp.mailgun.org",
    "port": 587,
    "user": "alex@outreach.acme.com",
    "pass": "••••••••••••"
  },
  "imap": {
    "host": "imap.mailgun.org",
    "port": 993,
    "user": "alex@outreach.acme.com",
    "pass": "••••••••••••"
  },
  "warmup": {
    "enabled": true,
    "ramp_per_day": 2,
    "target_daily_volume": 40
  }
}
200 OK Responseapplication/json
{
  "id": "mbx_01HQZ911",
  "email": "alex@outreach.acme.com",
  "status": "warming",
  "health_score": 100.0,
  "created_at": "2026-09-28T12:00:00Z"
}
POST/v1/mailboxes/:id/quarantine
Scope: mailboxes:write
Quarantine Mailbox

Instantly pause all campaign sends on a mailbox while keeping safe warmup active to recover reputation.

Parameters
id(string)Required
Mailbox ID (e.g. mbx_01HQX892)
Request Body (JSON)
{
  "reason": "Sudden bounce rate spike detected",
  "auto_recover": true
}
200 OK Responseapplication/json
{
  "id": "mbx_01HQX892",
  "status": "quarantined",
  "quarantined_at": "2026-09-28T14:30:00Z",
  "campaigns_paused": 3
}

Campaigns & Sequences

Launch multi-step automated outreach sequences with custom branching, A/B testing, and pool rotation.

GET/v1/campaigns
Scope: sequences:read
List Campaigns

List all campaigns with delivery metrics, open rates, and reply statistics.

200 OK Responseapplication/json
{
  "data": [
    {
      "id": "cmp_01HQW431",
      "name": "Q3 SaaS Founders Outreach",
      "status": "running",
      "stats": {
        "leads_count": 1250,
        "sent": 820,
        "opened": 541,
        "replied": 98,
        "bounced": 4,
        "open_rate": 0.659,
        "reply_rate": 0.119
      },
      "mailbox_pool": ["mbx_01HQX892", "mbx_01HQZ911"],
      "created_at": "2026-09-20T08:00:00Z"
    }
  ]
}
POST/v1/campaigns
Scope: sequences:write
Create Campaign

Create a new multi-step cold email campaign with dynamic delay conditions and variant templates.

Request Body (JSON)
{
  "name": "Enterprise CTO Inbound Follow-up",
  "mailbox_ids": ["mbx_01HQX892", "mbx_01HQZ911"],
  "schedule": {
    "timezone": "America/New_York",
    "days": [1, 2, 3, 4, 5],
    "hours": { "start": 9, "end": 17 }
  },
  "steps": [
    {
      "step_number": 1,
      "delay_days": 0,
      "subject": "Quick question on {{company}}'s deliverability stack",
      "body": "Hi {{first_name}},\n\nSaw you manage infrastructure at {{company}}..."
    },
    {
      "step_number": 2,
      "delay_days": 3,
      "subject": "Re: Quick question on {{company}}'s deliverability stack",
      "body": "Following up to see if deliverability was on your roadmap this quarter..."
    }
  ]
}
200 OK Responseapplication/json
{
  "id": "cmp_01HQY772",
  "name": "Enterprise CTO Inbound Follow-up",
  "status": "draft",
  "steps_count": 2,
  "created_at": "2026-09-28T15:00:00Z"
}
POST/v1/campaigns/:id/launch
Scope: sequences:write
Launch Campaign

Dispatches campaign sequence execution to distributed sender workers.

200 OK Responseapplication/json
{
  "id": "cmp_01HQY772",
  "status": "running",
  "dispatched_to_workers": 2,
  "queued_sends": 450
}

Contacts & Audience

Manage prospect lists, custom attributes, verification states, and workspace suppression lists.

POST/v1/contacts/batch
Scope: contacts:write
Batch Import Contacts

Upload up to 5,000 contacts at once with custom variable fields for sequencing.

Request Body (JSON)
{
  "contacts": [
    {
      "email": "elon@acme.com",
      "first_name": "Elon",
      "last_name": "Musk",
      "company": "Acme Corp",
      "custom_fields": {
        "title": "VP of Engineering",
        "tech_stack": "PostgreSQL, Go"
      }
    }
  ]
}
200 OK Responseapplication/json
{
  "imported": 1,
  "duplicates_skipped": 0,
  "invalid_skipped": 0
}
POST/v1/suppression
Scope: contacts:write
Add to Suppression List

Permanently prevent sending to an email address or whole domain across all campaigns.

Request Body (JSON)
{
  "type": "email",
  "value": "donotcontact@competitor.com",
  "reason": "manual_request"
}
200 OK Responseapplication/json
{
  "id": "sup_01HQK300",
  "value": "donotcontact@competitor.com",
  "created_at": "2026-09-28T15:30:00Z"
}

Unified Inbox & AI Triage

Access consolidated inbound email replies, automatic sentiment tagging, and thread management.

GET/v1/inbox/threads
Scope: crm:read
List Reply Threads

Get recent replies across all sender accounts classified into Interested, Meeting, OOO, or Not Interested.

Parameters
category(string)
Filter by AI category: interested, meeting, ooo, objection
campaign_id(string)
Filter by specific campaign ID
200 OK Responseapplication/json
{
  "data": [
    {
      "id": "thd_01HQK899",
      "mailbox_id": "mbx_01HQX892",
      "campaign_id": "cmp_01HQW431",
      "contact_email": "tim@apple.com",
      "subject": "Re: Quick question on Apple's deliverability stack",
      "snippet": "Yes, let's chat next Tuesday at 2pm EST...",
      "classification": "meeting_requested",
      "sentiment_score": 0.94,
      "last_message_at": "2026-09-28T14:15:00Z"
    }
  ]
}
POST/v1/inbox/threads/:id/reply
Scope: crm:write
Send Reply via Connected Mailbox

Send an authenticated direct reply to an email thread directly through the origin sender mailbox.

Request Body (JSON)
{
  "body": "Hi Tim, Tuesday at 2pm EST works great. Calendar invite sent!"
}
200 OK Responseapplication/json
{
  "id": "msg_01HQP900",
  "status": "sent",
  "sent_at": "2026-09-28T14:20:00Z"
}

Webhooks & Event Stream

Receive signed real-time events for replies, deliverability signals, bounces, and mailbox state changes.

POST/v1/webhooks
Scope: admin:write
Create Webhook Subscription

Register an HTTPS endpoint with HMAC-SHA256 signature verification.

Request Body (JSON)
{
  "url": "https://api.yourcompany.com/webhooks/mailfor",
  "events": [
    "reply.received",
    "reply.classified",
    "bounce.hard",
    "mailbox.quarantined"
  ]
}
200 OK Responseapplication/json
{
  "id": "whk_01HQA551",
  "url": "https://api.yourcompany.com/webhooks/mailfor",
  "secret": "whsec_9d41kk8832a00b19283f...",
  "status": "active",
  "events": ["reply.received", "reply.classified", "bounce.hard", "mailbox.quarantined"]
}
05 · Real-time Streaming

Webhooks & HMAC Verification

MailFor signs every webhook request with an HMAC-SHA256 digest using your endpoint's signing secret.

Verify signature in Node.js / Express:
import crypto from 'crypto';

function verifyWebhook(req, secret) {
  const signature = req.headers['x-mailfor-signature'];
  const timestamp = req.headers['x-mailfor-timestamp'];
  const payload = req.rawBody;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Supported Event Catalog

Event NameCategoryTrigger Description
reply.receivedInboundFires when a recipient responds to any campaign email.
reply.classifiedAI TriageFires when the NLP engine categorizes reply sentiment (Interested, Meeting, OOO).
bounce.hardDeliverabilityFires when an address is invalid. Auto-added to workspace suppression list.
bounce.softDeliverabilityFires on temporary mailbox provider rejections (mailbox full, throttling).
complaint.receivedDeliverabilityFires on spam complaint. Mailbox volume is instantly throttled.
mailbox.quarantinedSafetyFires when health drops below safety threshold (90%). Sends paused.
sequence.startedCampaignsFires when a contact starts a multi-step sequence.
deal.stage_changedCRMFires when prospect pipeline stage advances.
06 · Specifications

Errors & Rate Limits

Standard rate limits are 600 requests / min per API key. Every error response returns a typed code and a human-readable description.

400 Bad Request
{
  "error": {
    "code": "invalid_parameter",
    "message": "email address format is invalid",
    "param": "email"
  }
}
429 Rate Limited
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Key exceeded 600 req/min limit",
    "retry_after": 12
  }
}