API Documentation

Complete reference for the FlushIt REST API. All endpoints use JSON request and response bodies.

Authentication

All API requests must include your API key in the X-API-Key header. Generate keys from Dashboard > API Keys.

cURL Example

curl -H "X-API-Key: your_api_key_here" \
  https://flushit.app/api/credits/balance

JavaScript Example

const res = await fetch("https://flushit.app/api/credits/balance", {
  headers: { "X-API-Key": "your_api_key_here" }
});
const data = await res.json();

Base URL: https://flushit.app

Authentication

All API requests require an API key. Include your key in the X-API-Key header with every request. Generate API keys from the Dashboard under API Keys.

GET/api/auth/me

Returns the authenticated user profile associated with the API key.

Response

{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "role": "user",
    "creditBalance": 5000,
    "createdAt": "2025-12-01T00:00:00Z"
  }
}

Credits

Check your credit balance and transaction history. 1 credit = 1 email or 1 SMS. Credits never expire.

GET/api/credits/balance

Returns the current credit balance for the authenticated user.

Response

{
  "balance": 5000,
  "reserved": 150,
  "available": 4850
}
GET/api/credits/transactions

Returns credit transaction history with pagination.

Response

{
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "purchase",
      "amount": 1000,
      "description": "Credit purchase via BTC",
      "createdAt": "2025-12-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1
}

Sending

Send email and SMS campaigns. Credits are reserved atomically before sending begins. Failed deliveries are automatically refunded.

POST/api/send

Create and send a new email or SMS campaign.

Request Body

{
  "type": "email",
  "from": "sender@yourdomain.com",
  "subject": "Hello from FlushIt",
  "htmlContent": "<h1>Welcome!</h1><p>Your message here.</p>",
  "recipients": [
    "user1@example.com",
    "user2@example.com"
  ],
  "trackOpens": true,
  "trackClicks": true
}

Response

{
  "jobId": "job_abc123",
  "status": "queued",
  "totalRecipients": 2,
  "creditsReserved": 2,
  "estimatedDelivery": "2025-12-15T10:35:00Z"
}
GET/api/send/:jobId

Get the status and delivery details for a specific send job.

Response

{
  "job": {
    "id": "job_abc123",
    "status": "completed",
    "type": "email",
    "totalRecipients": 2,
    "sentCount": 2,
    "failedCount": 0,
    "creditsCharged": 2,
    "creditsRefunded": 0,
    "createdAt": "2025-12-15T10:30:00Z"
  }
}

Templates

Create, manage, and use reusable email templates. Supports raw HTML, SendGrid dynamic templates, and AI-generated templates.

GET/api/templates

List all templates for the authenticated user.

Response

{
  "templates": [
    {
      "id": "tpl_abc123",
      "name": "Welcome Email",
      "type": "html",
      "subject": "Welcome!",
      "createdAt": "2025-12-10T08:00:00Z"
    }
  ]
}
POST/api/templates

Create a new template.

Request Body

{
  "name": "Welcome Email",
  "type": "html",
  "subject": "Welcome to FlushIt!",
  "htmlContent": "<h1>Welcome!</h1>"
}

Response

{
  "template": {
    "id": "tpl_abc123",
    "name": "Welcome Email",
    "type": "html",
    "subject": "Welcome to FlushIt!",
    "createdAt": "2025-12-10T08:00:00Z"
  }
}
DELETE/api/templates/:id

Delete a template by ID.

Response

{
  "success": true
}

Contacts

Manage contact lists and recipients. Import contacts in bulk or add them individually.

GET/api/contacts

List all contacts with optional search and pagination.

Response

{
  "contacts": [
    {
      "id": "ct_abc123",
      "email": "user@example.com",
      "tags": ["newsletter", "premium"],
      "createdAt": "2025-12-01T00:00:00Z"
    }
  ],
  "total": 1500,
  "page": 1
}
POST/api/contacts

Add a new contact or import contacts in bulk.

Request Body

{
  "contacts": [
    { "email": "new@example.com", "tags": ["imported"] }
  ]
}

Response

{
  "imported": 1,
  "duplicates": 0,
  "errors": 0
}
DELETE/api/contacts/:id

Remove a contact by ID.

Response

{
  "success": true
}

Domains

Verify custom sending domains with DNS records. Improves deliverability with DKIM, SPF, and DMARC authentication.

GET/api/domains

List all domains and their verification status.

Response

{
  "domains": [
    {
      "id": "dom_abc123",
      "domain": "yourdomain.com",
      "verified": true,
      "dkimConfigured": true,
      "createdAt": "2025-12-05T00:00:00Z"
    }
  ]
}
POST/api/domains

Add a new domain for verification.

Request Body

{
  "domain": "yourdomain.com"
}

Response

{
  "domain": {
    "id": "dom_abc123",
    "domain": "yourdomain.com",
    "verified": false,
    "dnsRecords": [
      {
        "type": "TXT",
        "host": "_flushit.yourdomain.com",
        "value": "flushit-verify=abc123"
      }
    ]
  }
}
POST/api/domains/:id/verify

Trigger DNS verification for a domain.

Response

{
  "verified": true,
  "dkimConfigured": true
}

Webhooks

Receive real-time HTTP callbacks for delivery events. All webhook payloads are signed with HMAC-SHA256.

GET/api/webhooks

List all configured webhooks.

Response

{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://your-server.com/webhook",
      "events": ["delivery.sent", "delivery.bounced"],
      "active": true,
      "createdAt": "2025-12-20T00:00:00Z"
    }
  ]
}
POST/api/webhooks

Create a new webhook endpoint. Returns a signing secret (shown only once).

Request Body

{
  "url": "https://your-server.com/webhook",
  "events": ["delivery.sent", "delivery.bounced", "campaign.completed"]
}

Response

{
  "webhook": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook",
    "events": ["delivery.sent", "delivery.bounced", "campaign.completed"],
    "active": true
  },
  "secret": "whsec_abc123def456..."
}
DELETE/api/webhooks/:id

Delete a webhook endpoint.

Response

{
  "success": true
}

Tracking

Access open and click tracking data for your campaigns. Tracking is per-recipient and includes timestamps.

GET/api/tracking/:jobId

Get tracking data for a specific send job.

Response

{
  "jobId": "job_abc123",
  "tracking": {
    "opens": {
      "total": 145,
      "unique": 120,
      "rate": 0.60
    },
    "clicks": {
      "total": 89,
      "unique": 72,
      "rate": 0.36
    },
    "recipients": [
      {
        "email": "user@example.com",
        "status": "delivered",
        "openedAt": "2025-12-15T11:00:00Z",
        "clickedAt": "2025-12-15T11:02:00Z"
      }
    ]
  }
}

Rate Limiting

API requests are rate-limited per API key. Current limits:

100

Requests / minute

5,000

Requests / hour

50,000

Requests / day

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Codes

400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
429Too Many Requests - Rate limited
500Internal Server Error - Contact support
AboutStatusChangelogHome