API Documentation

Everything you need to integrate MailWok into your application. Send transactional emails, manage contacts, and run campaigns via our REST API or SMTP relay.

Overview

The MailWok API is organized around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

• JSON API — All requests and responses use application/json
• Authentication — API keys via Bearer token in the Authorization header
• Rate Limiting — 100 requests/second for Standard, 500/s for Professional
• Versioning — Current version is v1

Authentication

Authenticate your API requests by including your API key in the Authorization header. You can find your API key in your dashboard settings.

Authorization: Bearer mwk_live_xxxxxxxxxxxxxxxxxxxx

Quick Start

Send your first email in under 2 minutes. Install the SDK and make a single API call.

Install SDK

# Node.js
npm install @mailwok/sdk

# Python
pip install mailwok

# PHP
composer require mailwok/sdk

Send your first email

const { MailWok } = require('@mailwok/sdk');

const client = new MailWok('mwk_live_your_api_key');

const result = await client.send({
  from: 'you@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Welcome to our platform!',
  html: '<h1>Hello {{name}}</h1>',
  data: { name: 'Alex' }
});

console.log(result.messageId);
// → "msg_a1b2c3d4e5f6"

Send an Email

Request Body

{
  "success": true,
  "message_id": "msg_a1b2c3d4e5f6",
  "status": "queued",
  "estimated_delivery": "<200ms"
}

SMTP Configuration

Use MailWok as your SMTP relay. Works with any application or framework that supports SMTP.

Laravel Example

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailwok.com
MAIL_PORT=587
MAIL_USERNAME=mwk_live_your_api_key
MAIL_PASSWORD=mwk_live_your_api_key
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=you@yourdomain.com
MAIL_FROM_NAME="Your App"

Event Webhooks

MailWok sends webhook notifications for email events in real-time. Configure webhook URLs in your dashboard.

Supported Events

Webhook Payload

{
  "event": "email.delivered",
  "timestamp": "2025-01-15T10:30:00Z",
  "message_id": "msg_a1b2c3d4e5f6",
  "recipient": "user@example.com",
  "metadata": {
    "tags": ["welcome", "onboarding"],
    "ip": "192.168.1.1",
    "user_agent": "Gmail/1.0"
  }
}

SDK Libraries

Official SDK libraries for popular languages. All SDKs are open-source and available on GitHub.

Rate Limits

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.