API Reference

Complete API reference for the FormaMail REST API.

Introduction

The FormaMail API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://api.formamail.com

Authentication

The FormaMail API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

# Example request with authentication
curl https://api.formamail.com/api/emails/send \
  -H "Authorization: Bearer fm_sk_abc123xyz456..." \
  -H "Content-Type: application/json"

API Sections

Core Resources

• Authentication - Login, signup, token management
• Emails - Send emails, view logs, manage delivery
• Templates - Create and manage email templates
• Attachments - Generate PDF and Excel files

Analytics & Monitoring

• Analytics - Email performance metrics and statistics

Account Management

• API Keys - Manage API authentication keys
• Teams - Team and member management
• Users - User account operations

Reference

• Error Codes - Complete list of error codes and meanings

Request Format

All POST requests should use JSON format with the Content-Type: application/json header:

POST /api/emails/send
Content-Type: application/json
Authorization: Bearer fm_sk_abc123xyz456...
 
{
  "templateId": "your-template-id",
  "to": [
    {
      "email": "recipient@example.com",
      "name": "John Doe"
    }
  ],
  "variables": {
    "firstName": "John",
    "orderNumber": "ORD-12345"
  }
}

Response Format

All API responses are returned in JSON format:

{
  "id": "email_abc123",
  "status": "sent",
  "createdAt": "2025-11-06T10:30:00Z"
}

Pagination

List endpoints return paginated results. Use the page and limit parameters:

GET /api/emails?page=1&limit=20

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Rate Limiting

The API implements rate limiting to ensure fair usage:

Note: FormaMail uses pay-as-you-go block pricing. Your email sending capacity is based on your purchased email credits, not a subscription tier. Contact us for custom rate limits for high-volume use cases.

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1699276800

Errors

The API uses standard HTTP status codes:

Error responses include details:

{
  "statusCode": 400,
  "code": "ERR_EMAIL_001",
  "message": "Invalid recipient email address",
  "timestamp": "2025-11-06T10:30:00Z",
  "path": "/api/emails/send"
}

See Error Codes for complete list.

Versioning

The current API version is v1. All endpoints are prefixed with /api/:

https://api.formamail.com/api/emails/send

Testing

Use the API Playground to test endpoints interactively without writing code.

For local testing, use MailHog (included in our Docker setup) to capture emails:

http://localhost:8025

Need Help?

• 💻 Try the API Playground
• 📖 Read the Developer Guide
• 💬 Join our Discord Community
• 📧 Email: api@formamail.com

Ready to explore? → Choose an API section from the sidebar