API Endpoints

The mailiam API provides RESTful endpoints for managing forms, sending emails, and processing submissions.

Base URL

https://api.mailiam.io

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.mailiam.io/api/forms

Form Submission

POST /submit/{formId}

Submit data to a form endpoint.

curl -X POST https://api.mailiam.io/submit/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello world"
  }'

Response:

{
  "success": true,
  "message": "Form submitted successfully"
}

Form Management

GET /api/forms

List all forms for your account.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.mailiam.io/api/forms

Response:

{
  "forms": [
    {
      "id": "contact",
      "name": "Contact Form",
      "submissions": 42,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /api/forms

Create a new form.

curl -X POST https://api.mailiam.io/api/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Signup",
    "to": "admin@example.com",
    "subject": "New Newsletter Subscription"
  }'

Email Sending

POST /api/email/send

Send a transactional email.

curl -X POST https://api.mailiam.io/api/email/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome!",
    "template": "welcome",
    "data": {
      "name": "John Doe"
    }
  }'

Billing

POST /api/billing/customer

Create a new customer for billing purposes.

curl -X POST https://api.mailiam.io/api/billing/customer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "John Doe",
    "tenantId": "tenant_123"
  }'

Response:

{
  "id": "cust_123",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2024-01-15T10:00:00Z"
}

POST /api/billing/subscription

Create a subscription for a customer with one of the available plans (starter, developer, scale).

curl -X POST https://api.mailiam.io/api/billing/subscription \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_123",
    "plan": "starter"
  }'

Response:

{
  "id": "sub_123",
  "customer_id": "cust_123",
  "plan": "starter",
  "status": "active",
  "created_at": "2024-01-15T10:05:00Z"
}

PATCH /api/billing/subscription/change

Change the current subscription plan.

curl -X PATCH https://api.mailiam.io/api/billing/subscription/change \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_123",
    "newPlan": "developer"
  }'

DELETE /api/billing/subscription

Cancel a subscription.

curl -X DELETE https://api.mailiam.io/api/billing/subscription \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_123"
  }'

POST /api/billing/usage

Record email usage for billing purposes.

curl -X POST https://api.mailiam.io/api/billing/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_123",
    "emailCount": 50
  }'

Response:

{
  "emailsRecorded": 50,
  "currentPeriodEmails": 5234,
  "includedEmails": 10000,
  "overage": 0,
  "plan": "developer"
}

GET /api/billing/info

Get current billing information for a customer, including usage and overage charges.

curl https://api.mailiam.io/api/billing/info \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_123"
  }'

Response:

{
  "tenantId": "tenant_123",
  "plan": "developer",
  "status": "active",
  "monthlyFee": 19.00,
  "includedEmails": 10000,
  "currentPeriod": {
    "emailsSent": 5234,
    "emailsIncluded": 10000,
    "overage": 0,
    "overageCost": 0.00
  },
  "totalEmailsSent": 15234,
  "createdAt": "2024-01-15T10:00:00Z",
  "lastEmailSent": "2024-01-20T14:30:00Z"
}

Error Responses

All endpoints return consistent error responses:

{
  "error": true,
  "message": "Invalid API key",
  "code": 401
}

Rate Limits

• Free Plan: 100 requests/hour
• Pro Plan: 1,000 requests/hour
• Enterprise: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200