API Documentation

The SelfIAM Mailer API is a RESTful service for sending emails and managing API keys. All requests and responses use JSON.

https://mailer.selfiam.site/api/v1

The official Node.js / TypeScript SDK wraps every API endpoint into a typed client. Install it with:

npm install selfiam-mailer

Quick Start

import { SelfIAMMailer } from "selfiam-mailer";

const mailer = new SelfIAMMailer({
  apiKey: "sk_live_YOUR_API_KEY",
});

const result = await mailer.send({
  to: "user@example.com",
  subject: "Hello!",
  body: "Sent via the npm SDK.",
});

console.log(result.emailId);
console.log(result.rateLimit?.remaining);

Methods

Configuration

const mailer = new SelfIAMMailer({
  apiKey: "sk_live_...",          // Required
  baseUrl: "https://mailer.selfiam.site", // Optional
  timeout: 30000,                 // Optional (ms)
});

Full source & docs: npmjs.com/package/selfiam-mailer

All API requests require a valid API key sent as a Bearer token in the Authorization header. You can create and manage API keys from the dashboard.

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxx

Requests without a valid token will receive a 401 Unauthorized response with the error code AUTH_001.

Sends an email. This is the primary endpoint of the Service.

Request Body

Example Request

curl -X POST https://mailer.selfiam.site/api/v1/send \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from SelfIAM Mailer",
    "body": "This is a test email sent via the API.",
    "from_name": "My App"
  }'

Success Response200 OK

{
  "success": true,
  "emailId": "re_xxxxxxxxxxxx",
  "remaining": 24,
  "reset": "2026-08-20T00:00:00.000Z"
}

Error Response400 / 401 / 429 / 500

{
  "success": false,
  "error": "Validation failed",
  "code": "VAL_001",
  "details": {
    "fieldErrors": {
      "to": ["Invalid email"]
    }
  }
}

Lists all API keys associated with the authenticated user. Returns key metadata only — raw keys are never returned.

Requires session-based authentication.

Example Request

curl https://mailer.selfiam.site/api/v1/keys \
  -H "Authorization: Bearer session_token"

Response200 OK

{
  "success": true,
  "keys": [
    {
      "_id": "64a1b2c3d4e5f6a7b8c9d0e1",
      "key_prefix": "sk_a1b2",
      "name": "Production",
      "is_active": true,
      "created_at": "2026-08-15T10:30:00.000Z"
    }
  ]
}

Creates a new API key. The raw key is returned exactly once in the response. Store it securely — it cannot be retrieved later.

Requires session-based authentication. Subject to max active keys limit per user.

Request Body

Example Request

curl -X POST https://mailer.selfiam.site/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production" }'

Response201 Created

{
  "success": true,
  "rawKey": "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "name": "Production"
}

Revokes (deactivates) an API key. The key will immediately stop working for all future requests.

Requires session-based authentication. You can only revoke your own keys.

Path Parameters

Example Request

curl -X DELETE https://mailer.selfiam.site/api/v1/keys/64a1b2c3d4e5f6a7b8c9d0e1

Response200 OK

{
  "success": true
}

Lists the most recent emails sent through the authenticated user's API keys. Returns up to 100 entries sorted by creation date (newest first).

Requires session-based authentication.

Example Request

curl https://mailer.selfiam.site/api/v1/emails

Response200 OK

{
  "success": true,
  "emails": [
    {
      "_id": "64a1b2c3d4e5f6a7b8c9d0e2",
      "to": "recipient@example.com",
      "from_name": "My App",
      "subject": "Hello from SelfIAM Mailer",
      "status": "sent",
      "created_at": "2026-08-19T14:22:00.000Z",
      "body": "This is a test email sent via the API.",
      "html": "<p>This is a test email sent via the API.</p>"
    }
  ]
}

All error responses include a code field for programmatic handling.

The POST /api/v1/send endpoint is subject to a daily rate limit. The default limit is 25 requests per day per user. The limit resets at midnight UTC.

Response Headers

Example

HTTP/1.1 200 OK
X-RateLimit-Limit: 25
X-RateLimit-Remaining: 24
X-RateLimit-Reset: 2026-08-20T00:00:00.000Z

When you exceed the rate limit, the API returns 429 Too Many Requests with error code RATE_001. Wait until the reset time before retrying.