API Reference

Integrate Email Router with your applications using our REST API. Automate domain setup, alias creation, and ticket management.

API Keys

API keys are coming soon. For now, use session-based authentication through the dashboard.

Authentication

All API requests require authentication using your API key:

auth-example.sh

curl https://api.emailrouter.com/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Keep It Secret

Never expose your API key in client-side code or public repositories.

Base URL

text

https://api.emailrouter.com/v1

Domains API

List Domains

list-domains.json

GET /api/domains

Response:
{
  "domains": [
    {
      "id": "dom_abc123",
      "domain": "acme.com",
      "status": "active",
      "verified": true,
      "createdAt": "2024-02-20T10:00:00Z"
    }
  ]
}

Create Domain

create-domain.json

POST /api/domains

Request:
{
  "domain": "example.com"
}

Response:
{
  "id": "dom_xyz789",
  "domain": "example.com",
  "status": "pending_verification",
  "mxRecords": [
    { "priority": 10, "value": "mx1.resend.dev" },
    { "priority": 20, "value": "mx2.resend.dev" }
  ]
}

Get Domain

get-domain.json

GET /api/domains/{domainId}

Response:
{
  "id": "dom_abc123",
  "domain": "acme.com",
  "status": "active",
  "verified": true,
  "aliasCount": 5,
  "createdAt": "2024-02-20T10:00:00Z"
}

Integrations API

List Integrations

list-integrations.json

GET /api/integrations

Response:
{
  "integrations": [
    {
      "id": "int_abc123",
      "type": "slack",
      "name": "Customer Support",
      "createdAt": "2024-02-21T15:30:00Z"
    }
  ]
}

Create Integration

create-integration.json

POST /api/integrations

Request:
{
  "type": "slack",
  "name": "Sales Team",
  "webhookUrl": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
}

Response:
{
  "id": "int_xyz789",
  "type": "slack",
  "name": "Sales Team",
  "createdAt": "2024-02-28T10:00:00Z"
}

Aliases API

List Aliases

list-aliases.json

GET /api/aliases

Response:
{
  "aliases": [
    {
      "id": "alias_abc123",
      "email": "support@acme.com",
      "localPart": "support",
      "domainId": "dom_abc123",
      "integrationId": "int_abc123",
      "status": "active",
      "createdAt": "2024-02-22T09:00:00Z"
    }
  ]
}

Create Alias

create-alias.json

POST /api/aliases

Request:
{
  "domainId": "dom_abc123",
  "localPart": "billing",
  "integrationId": "int_xyz789"
}

Response:
{
  "id": "alias_xyz789",
  "email": "billing@acme.com",
  "localPart": "billing",
  "domainId": "dom_abc123",
  "integrationId": "int_xyz789",
  "status": "active",
  "createdAt": "2024-02-28T10:30:00Z"
}

Tickets API

List Tickets

list-tickets.json

GET /api/emails/tickets/mine

Response:
{
  "tickets": [
    {
      "id": "ticket_abc123",
      "from": "customer@email.com",
      "fromName": "John Doe",
      "subject": "Need help with billing",
      "status": "in_progress",
      "assignedTo": "user_456",
      "receivedAt": "2024-02-28T09:00:00Z"
    }
  ]
}

Claim Ticket

claim-ticket.json

POST /api/emails/tickets/{ticketId}/claim

Response:
{
  "id": "ticket_abc123",
  "status": "in_progress",
  "assignedTo": "user_456",
  "claimedAt": "2024-02-28T10:00:00Z"
}

Update Status

update-ticket-status.json

POST /api/emails/tickets/{ticketId}/status

Request:
{
  "status": "resolved"
}

Response:
{
  "id": "ticket_abc123",
  "status": "resolved",
  "resolvedAt": "2024-02-28T11:00:00Z"
}

Error Handling

The API uses standard HTTP status codes:

error-responses.json

200 - OK
201 - Created
400 - Bad Request (invalid parameters)
401 - Unauthorized (invalid API key)
404 - Not Found
429 - Too Many Requests (rate limited)
500 - Internal Server Error

Error Response:
{
  "error": {
    "code": "invalid_domain",
    "message": "Domain name is invalid"
  }
}

Rate Limits

API requests are rate limited:

100 requests/minute - Per API key
10,000 requests/day - Per workspace

Rate Limit Headers

Check response headers for rate limit status: X-RateLimit-Remaining and X-RateLimit-Reset

Chatbot Widget

Advanced