Introduction

Wistfare Mail API — send transactional emails, receive delivery webhooks, and manage audiences programmatically.

Wistfare Mail provides a simple REST API to send transactional emails from your applications. Domains, templates, and analytics are managed through the Wistfare Mail dashboard — the API is focused on what your code needs.

What the API Does

Feature	Description
Send Emails	Single and batch transactional email delivery with DKIM signing
Webhooks	Real-time notifications for delivery, bounce, open, and click events
Audiences	Manage contact lists and subscriptions for targeted sending
Domains	Add verified sending domains programmatically

Base URL

Wistfare Mail is self-hosted. Use your instance's base URL in all requests:

https://mail.wistfare.com/api/v1

Quick Example

import { WistMail } from 'wistmail'
 
const wm = new WistMail({
  apiKey: 'wm_your_api_key',
  baseUrl: 'https://mail.wistfare.com',
})
 
await wm.emails.send({
  from: 'hello@wistfare.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our platform</h1>',
})

Authentication

All API requests require an API key sent via the X-API-Key header:

X-API-Key: wm_your_api_key

Create API keys from Settings > API Keys in the Wistfare Mail dashboard. Each key has scopes that control access:

Scope	Access
`emails:send`	Send single and batch emails
`emails:read`	Read email delivery status
`contacts:manage`	Manage audiences and contacts
`webhooks:manage`	Configure webhook endpoints
`domains:manage`	Add and verify sending domains

Rate Limits

Default: 10 requests/second per API key
Batch endpoints: 5 requests/second

Rate limit headers are included in every response:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1711584000

Error Format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address"
  }
}

See the Errors Reference for a complete list of error codes.