Email

Overview

The /api/v1/emails/create endpoint allows users to create email addresses programmatically using API key authentication.

Playground

You can try the API endpoints in the Email API Playground.

Authentication

Use your API key in one of two ways:

Authorization Header (Recommended):
```
Authorization: Bearer YOUR_API_KEY
```
Query Parameter:
```
?key=YOUR_API_KEY
```

Rate Limits

Rate limits are automatically configured based on your subscription tier:

Free Plan: 200 requests per hour
Pro Plan: 2000 requests per hour
Lifetime Plan: 2000 requests per hour

Endpoint

POST /api/v1/emails/create

Request Body

{
  "email": "myemail@ig.do",
  "tag": "personal"
}

Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Full email address (4-64 characters for prefix, valid format)
`tag`	string	No	Tag for categorization (max 50 characters)

Domain Access

Access to domains is based on your subscription tier:

Free Domains (ig.do): Available to all users
Pro Domains (kfc.sh, uv.do): Requires Pro subscription or Lifetime plan

If you attempt to use a Pro domain without proper subscription, you'll receive a 403 error.

Response

Success (201 Created)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "myemail@ig.do",
    "tag": "personal",
    "like": false,
    "pin": false,
    "createdAt": "2025-12-07T12:00:00.000Z"
  }
}

Error Responses

401 Unauthorized - Missing API Key

{
  "success": false,
  "error": "Missing API key. Provide it via Authorization header (Bearer token) or ?key= query parameter"
}

401 Unauthorized - Invalid API Key

{
  "success": false,
  "error": "Invalid or expired API key: [error details]"
}

400 Bad Request - Invalid Data

{
  "success": false,
  "error": "Invalid request data",
  "details": [
    {
      "path": ["email"],
      "message": "Invalid email format"
    }
  ]
}

400 Bad Request - Invalid Email Prefix Length

{
  "success": false,
  "error": "Email prefix length must be between 4 and 64 characters"
}

400 Bad Request - Reserved Email Prefix

{
  "success": false,
  "error": "The provided email prefix is reserved. Please choose another one."
}

403 Forbidden - Domain Permission

{
  "success": false,
  "error": "You don't have permission to use the domain \"kfc.sh\". Premium domains require an active Pro subscription or Lifetime plan."
}

409 Conflict - Email Exists

{
  "success": false,
  "error": "An email address with this address already exists"
}

Examples

cURL

curl -X POST https://your-domain.com/api/v1/emails/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "myemail@ig.do",
    "tag": "personal"
  }'

JavaScript (Fetch)

const response = await fetch('https://your-domain.com/api/v1/emails/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'myemail@ig.do',
    tag: 'personal',
  }),
});

const data = await response.json();
console.log(data);

Python (requests)

import requests

url = 'https://your-domain.com/api/v1/emails/create'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}
data = {
    'email': 'myemail@ig.do',
    'tag': 'personal',
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Creating API Keys

Navigate to Settings > API Keys in your dashboard
Click Create API Key
Configure your rate limits:
- Free users: Up to 200 requests/hour
- Pro users: Up to 2000 requests/hour
Save your API key securely (it's only shown once)

Best Practices

Store API keys securely: Never commit API keys to version control
Use environment variables: Store keys in .env files or secure vaults
Monitor rate limits: Track your usage to avoid hitting limits
Validate email format: Ensure email addresses are properly formatted before creation
Handle errors gracefully: Implement proper error handling in your code
Use HTTPS: Always use secure connections for API requests

Notes

Email prefix must be between 4 and 64 characters
Email addresses are unique per user and domain
Reserved words (e.g., admin, noreply, postmaster) cannot be used as email prefixes
Soft-deleted email addresses are excluded from uniqueness checks
Created emails are automatically marked with the current timestamp