PostMTA
API Reference

REST API
Reference

Complete reference for all 71+ REST API endpoints. Authentication methods, request/response formats, and curl examples for every operation.

JWT + API Keys71+ EndpointsRate LimitedJSON APIOpenAPI Compatible
Authentication

Three Authentication Methods

PostMTA supports JWT Bearer tokens, API key headers, and API key Bearer tokens.

JWT Bearer Token

Obtain a JWT by logging in, then include it in the Authorization header.

# Login
curl -X POST /api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@co.com","password":"..."}'

# Use token
curl /api/v1/credits \
  -H "Authorization: Bearer eyJhbG..."

API Key (Header)

Create scoped API keys and use them via the X-API-Key header.

curl /api/v1/credits \
  -H "X-API-Key: pmta_a1b2c3d4_..."

API Key (Bearer)

API keys can also be used as Bearer tokens for convenience.

curl /api/v1/credits \
  -H "Authorization: Bearer pmta_a1b2c3d4_..."
Endpoints

Complete API Endpoint Reference

All API groups with HTTP methods, paths, and descriptions. Every endpoint returns JSON.

Health & Metrics

MethodPathDescription
GET/healthService health check (no auth required)
GET/metricsPrometheus and JSON metrics

Authentication

MethodPathDescription
POST/api/v1/auth/registerRegister a new user and organization
POST/api/v1/auth/loginLogin with email and password, returns JWT
GET/api/v1/auth/meGet current authenticated user details

Users

MethodPathDescription
GET/api/v1/usersList all users in organization
GET/api/v1/users/:idGet user details
PUT/api/v1/users/:id/roleUpdate user role

Credits

MethodPathDescription
GET/api/v1/creditsGet all credit balances
GET/api/v1/credits/:typeGet specific credit type balance
POST/api/v1/credits/consumeConsume credits
GET/api/v1/credits/usageCredit usage history
GET/api/v1/credits/packagesAvailable credit packages
GET/api/v1/credits/alertsCredit alert thresholds
POST/api/v1/credits/alertsSet credit alert threshold

API Keys

MethodPathDescription
POST/api/v1/api-keysCreate a new API key
GET/api/v1/api-keysList all API keys
GET/api/v1/api-keys/:idGet API key details
POST/api/v1/api-keys/:id/rotateRotate API key
DELETE/api/v1/api-keys/:idDelete an API key

Messages

MethodPathDescription
POST/api/v1/messages/sendSend a single email message
POST/api/v1/messages/batchSend up to 100 messages in one request
GET/api/v1/messagesList messages with pagination and filters
GET/api/v1/messages/:idGet message by ID
POST/api/v1/messages/:id/cancelCancel a queued message
POST/api/v1/messages/simulate-deliverySimulate delivery for testing

Queues

MethodPathDescription
GET/api/v1/queues/statusQueue status overview
GET/api/v1/queuesList all queues
POST/api/v1/queues/:id/:actionQueue action (flush, hold, release)

Domains

MethodPathDescription
POST/api/v1/domainsCreate domain with DKIM key generation
GET/api/v1/domainsList all domains
GET/api/v1/domains/:idGet domain details
POST/api/v1/domains/:id/verifyVerify domain DNS configuration
POST/api/v1/domains/:id/rotate-dkimRotate DKIM keys
PUT/api/v1/domains/:id/bimiUpdate BIMI configuration
DELETE/api/v1/domains/:idDelete a domain

vMTAs

MethodPathDescription
POST/api/v1/vmtasCreate a virtual MTA
GET/api/v1/vmtasList all vMTAs
GET/api/v1/vmtas/:idGet vMTA details
PUT/api/v1/vmtas/:idUpdate vMTA configuration
POST/api/v1/vmtas/:id/pausePause vMTA sending
POST/api/v1/vmtas/:id/resumeResume vMTA sending
GET/api/v1/vmtas/:id/warmupGet warmup status
GET/api/v1/vmtas/:id/queueGet vMTA queue status
DELETE/api/v1/vmtas/:idDelete a vMTA

Webhooks & Tracking

MethodPathDescription
POST/api/v1/webhooksCreate a webhook endpoint
GET/api/v1/webhooksList all webhooks
GET/api/v1/webhooks/:idGet webhook details
PUT/api/v1/webhooks/:idUpdate webhook configuration
POST/api/v1/webhooks/:id/testSend test event to webhook
GET/api/v1/webhooks/:id/deliveriesGet webhook delivery logs
DELETE/api/v1/webhooks/:idDelete a webhook
GET/track/open/:idOpen tracking pixel (1x1 transparent GIF)
GET/track/click/:tokenClick tracking redirect

Security

MethodPathDescription
GET/api/v1/security/statusSecurity system status overview
GET/api/v1/security/greylisting/statsGreylisting statistics
GET/api/v1/security/greylisting/configGreylisting configuration
POST/api/v1/security/dnsbl/checkCheck IP against DNS blocklists
GET/api/v1/security/dnsbl/blocklistsConfigured blocklists
POST/api/v1/security/dnsbl/clear-cacheClear DNSBL cache
POST/api/v1/security/spam-scoreAnalyze message spam score
POST/api/v1/security/av-scanScan attachment for viruses
GET/api/v1/security/auto-block/rulesList auto-block rules
POST/api/v1/security/auto-block/toggleToggle auto-block rule
GET/api/v1/security/auto-block/activeGet active blocks
POST/api/v1/security/auto-block/:id/resolveResolve an auto-block

Analytics

MethodPathDescription
GET/api/v1/analytics/summaryDelivery summary statistics
GET/api/v1/analytics/timeseriesTime-series delivery data
GET/api/v1/analytics/breakdownDelivery breakdown by dimension
GET/api/v1/analytics/ispISP-level delivery analytics
GET/api/v1/analytics/trendDelivery trend analysis
GET/api/v1/analytics/bounce-reasonsBounce reason categorization
GET/api/v1/analytics/reportGenerate delivery report
GET/api/v1/analytics/exportExport analytics as CSV

Billing

MethodPathDescription
GET/api/v1/billing/planGet current plan details
POST/api/v1/billing/upgradeUpgrade plan
POST/api/v1/billing/downgradeDowngrade plan
POST/api/v1/billing/checkoutCreate checkout session
GET/api/v1/billing/invoicesList invoices
GET/api/v1/billing/usage-rollupUsage rollup by period
GET/api/v1/billing/organizationGet organization billing details
Examples

Common API Operations

Curl examples for the most common API operations.

Send an Email

curl -X POST https://mail.yourdomain.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Hello from PostMTA",
    "html": "<h1>Hello!</h1><p>Test message.</p>",
    "track_opens": true,
    "track_clicks": true
  }'

Batch Send (100 messages)

curl -X POST https://mail.yourdomain.com/api/v1/messages/batch \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"from":"noreply@co.com","to":["a@test.com"],"subject":"Hi A","text":"Hello A"},
      {"from":"noreply@co.com","to":["b@test.com"],"subject":"Hi B","text":"Hello B"}
    ],
    "batch_id": "campaign_spring_2026"
  }'

Create Domain with DKIM

curl -X POST https://mail.yourdomain.com/api/v1/domains \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","dkim_selector":"pmta"}'

Check Credit Balances

curl -X GET https://mail.yourdomain.com/api/v1/credits \
  -H "Authorization: Bearer YOUR_JWT"

Analytics Summary (7 days)

curl -X GET "https://mail.yourdomain.com/api/v1/analytics/summary?period=7d" \
  -H "Authorization: Bearer YOUR_JWT"

Start Using the API

Deploy PostMTA and start sending email through the API in under 30 minutes. Built on KumoMTA for enterprise-grade performance.

Request a Demoarrow_forwardBack to Docs