API Reference

Send campaigns programmatically.

REST API with full email marketing capabilities. Manage contacts, create campaigns, send emails, and track results — all via API. $0.0003 per email sent.

Authentication

All API requests require an API key. Create one in your account settings at fairmail.ai/settings/api. API keys require a payment method on file.

bash 
curl -X POST https://api.faircompany.ai/v1/mail/campaigns \
  -H "Authorization: Bearer fmk_live_abc123..." \
  -H "Content-Type: application/json"
POST /v1/mail/contacts Free

Create Contact

Add a contact to your audience. Contacts are free to store — you only pay when you send them an email.

Request 
{
  "email": "sarah@example.com",
  "firstName": "Sarah",
  "lastName": "Chen",
  "tags": ["newsletter", "product-updates"],
  "customFields": {
    "company": "Acme Corp",
    "plan": "enterprise"
  }
}
Response — 201 Created 
{
  "id": "con_abc123",
  "email": "sarah@example.com",
  "firstName": "Sarah",
  "lastName": "Chen",
  "tags": ["newsletter", "product-updates"],
  "status": "subscribed",
  "createdAt": "2026-04-08T10:15:00Z"
}
POST /v1/mail/campaigns Free (creating)

Create Campaign

Create a new email campaign. Creating a campaign is free — you only pay when you send it ($0.0003 per recipient).

Request 
{
  "name": "March Newsletter",
  "subject": "What's new this month",
  "preheader": "Product updates, tips, and a surprise",
  "from": {
    "name": "Sarah at Acme",
    "email": "sarah@acme.com"
  },
  "audience": {
    "tags": ["newsletter"]
  },
  "content": {
    "html": "<html>...</html>"
  }
}
Response — 201 Created 
{
  "id": "cmp_xyz789",
  "name": "March Newsletter",
  "status": "draft",
  "audienceCount": 10240,
  "estimatedCost": 3.07,
  "createdAt": "2026-04-08T10:30:00Z"
}
POST /v1/mail/campaigns/:id/send $0.0003/recipient

Send Campaign

Send a draft campaign to its audience. Charges $0.0003 per email delivered. The estimated cost is shown when the campaign is created. A hold is placed on your wallet when you hit send.

Request 
{
  "scheduledAt": null
}
Response — 200 OK 
{
  "id": "cmp_xyz789",
  "status": "sending",
  "audienceCount": 10240,
  "cost": {
    "estimated": 3.07,
    "currency": "USD",
    "holdId": "hold_abc456"
  },
  "sentAt": "2026-04-08T10:35:00Z"
}

Per-Endpoint Pricing

Every API call that costs money shows the price upfront. Free endpoints are marked as such.

POST /v1/mail/campaigns/:id/send
$0.0003/recipient
POST /v1/mail/contacts
Free
GET /v1/mail/contacts
Free
POST /v1/mail/contacts/import
Free
POST /v1/mail/campaigns
Free
GET /v1/mail/campaigns/:id
Free
GET /v1/mail/campaigns/:id/stats
Free

Webhook Events

Configure webhooks to receive real-time notifications when emails are delivered, opened, clicked, bounced, or unsubscribed.

campaign.sent Campaign started sending
campaign.completed All emails delivered
email.delivered Email accepted by recipient server
email.opened Recipient opened the email
email.clicked Recipient clicked a link
email.bounced Email bounced (hard or soft)
email.complained Recipient marked as spam
contact.unsubscribed Contact unsubscribed from list