Email API

Overview

The Email API allows you to programmatically manage temporary email addresses, retrieve inbox messages, and view email details using API key authentication.

Playground

You can try all 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: 5000 requests per hour

Quota Limits

Email address creation is subject to monthly quotas based on your subscription tier:

Free Plan: 50 email addresses per month
Pro Plan: 1,000 email addresses per month
Lifetime Plan: Unlimited email addresses

Endpoints

1. Create Email Address

POST /api/v1/emails/create

Creates a new email address for the authenticated user.

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)

Success Response (201)

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

Error Responses

403 Forbidden - Monthly quota limit reached
409 Conflict - Email address already exists
400 Bad Request - Invalid email format or reserved prefix

2. List Email Addresses

GET /api/v1/emails

Retrieves a paginated list of email addresses for the authenticated user.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	number	No	1	Page number for pagination
`pageSize`	number	No	20	Number of items per page (max 100)
`email`	string	No	-	Filter by email address (fuzzy search)

Example Request

GET /api/v1/emails?page=1&pageSize=20&email=test

Success Response (200)

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "test123@ig.do",
      "tag": "personal",
      "like": false,
      "pin": false,
      "createdAt": "2026-01-02T12:00:00.000Z",
      "updatedAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 45,
    "totalPages": 3
  }
}

3. Get Email Address by ID

GET /api/v1/emails/:id

Retrieves details for a specific email address including inbox statistics.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Email address ID

Success Response (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "test123@ig.do",
    "tag": "personal",
    "like": false,
    "pin": false,
    "createdAt": "2026-01-02T12:00:00.000Z",
    "updatedAt": "2026-01-02T12:00:00.000Z",
    "stats": {
      "total": 15,
      "unread": 3
    }
  }
}

Error Responses

404 Not Found - Email address not found or does not belong to you

4. Get Inbox Emails

GET /api/v1/emails/:id/inbox

Retrieves inbox emails for a specific email address with folder filtering.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Email address ID

Query Parameters

Parameter	Type	Required	Default	Description
`folder`	string	No	inbox	Folder type: `inbox`, `starred`, `archive`, `trash`
`page`	number	No	1	Page number for pagination
`pageSize`	number	No	50	Number of items per page (max 100)

Example Request

GET /api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox?folder=inbox&page=1&pageSize=20

Success Response (200)

{
  "success": true,
  "data": [
    {
      "id": "msg-123",
      "from": "sender@example.com",
      "to": "test123@ig.do",
      "subject": "Welcome!",
      "text": "Welcome to our service",
      "html": "<p>Welcome to our service</p>",
      "readAt": null,
      "like": false,
      "tag": null,
      "createdAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 15,
    "totalPages": 1
  }
}

5. Get Message Details

GET /api/v1/emails/:id/inbox/:messageId

Retrieves the full details of a specific email message.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Email address ID
`messageId`	string	Yes	Message ID

Success Response (200)

{
  "success": true,
  "data": {
    "id": "msg-123",
    "from": "sender@example.com",
    "to": "test123@ig.do",
    "subject": "Welcome!",
    "text": "Welcome to our service",
    "html": "<p>Welcome to our service</p>",
    "headers": {},
    "readAt": "2026-01-02T13:00:00.000Z",
    "like": false,
    "tag": null,
    "createdAt": "2026-01-02T12:00:00.000Z",
    "updatedAt": "2026-01-02T13:00:00.000Z"
  }
}

Error Responses

404 Not Found - Email address or message not found

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.

Code Examples

cURL - Create Email

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

cURL - List Emails

curl -X GET "https://like.do/api/v1/emails?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript - Get Inbox

const response = await fetch(
  'https://like.do/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox?folder=inbox',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

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

Python - Get Message Details

import requests

url = 'https://like.do/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox/msg-123'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
}

response = requests.get(url, headers=headers)
print(response.json())

Creating API Keys

Navigate to Settings > API Keys in your dashboard
Click Create API Key
Configure your rate limits based on your plan
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
Check quota limits: Monitor your monthly email creation quota
Implement pagination: Use pagination for listing large numbers of emails

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
All timestamps are in ISO 8601 format (UTC)
Folders: inbox (default), starred (liked emails), archive (archived), trash (deleted)

Overview

The Email API allows you to programmatically manage temporary email addresses, retrieve inbox messages, and view email details using API key authentication.

Playground

You can try all 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: 5000 requests per hour

Quota Limits

Email address creation is subject to monthly quotas based on your subscription tier:

Free Plan: 50 email addresses per month
Pro Plan: 1,000 email addresses per month
Lifetime Plan: Unlimited email addresses

Endpoints

1. Create Email Address

POST /api/v1/emails/create

Creates a new email address for the authenticated user.

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)

Success Response (201)

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

Error Responses

403 Forbidden - Monthly quota limit reached
409 Conflict - Email address already exists
400 Bad Request - Invalid email format or reserved prefix

2. List Email Addresses

GET /api/v1/emails

Retrieves a paginated list of email addresses for the authenticated user.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	number	No	1	Page number for pagination
`pageSize`	number	No	20	Number of items per page (max 100)
`email`	string	No	-	Filter by email address (fuzzy search)

Example Request

GET /api/v1/emails?page=1&pageSize=20&email=test

Success Response (200)

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "test123@ig.do",
      "tag": "personal",
      "like": false,
      "pin": false,
      "createdAt": "2026-01-02T12:00:00.000Z",
      "updatedAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 45,
    "totalPages": 3
  }
}

3. Get Email Address by ID

GET /api/v1/emails/:id

Retrieves details for a specific email address including inbox statistics.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Email address ID

Success Response (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "test123@ig.do",
    "tag": "personal",
    "like": false,
    "pin": false,
    "createdAt": "2026-01-02T12:00:00.000Z",
    "updatedAt": "2026-01-02T12:00:00.000Z",
    "stats": {
      "total": 15,
      "unread": 3
    }
  }
}

Error Responses

404 Not Found - Email address not found or does not belong to you

4. Get Inbox Emails

GET /api/v1/emails/:id/inbox

Retrieves inbox emails for a specific email address with folder filtering.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Email address ID

Query Parameters

Parameter	Type	Required	Default	Description
`folder`	string	No	inbox	Folder type: `inbox`, `starred`, `archive`, `trash`
`page`	number	No	1	Page number for pagination
`pageSize`	number	No	50	Number of items per page (max 100)

Example Request

GET /api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox?folder=inbox&page=1&pageSize=20

Success Response (200)

{
  "success": true,
  "data": [
    {
      "id": "msg-123",
      "from": "sender@example.com",
      "to": "test123@ig.do",
      "subject": "Welcome!",
      "text": "Welcome to our service",
      "html": "<p>Welcome to our service</p>",
      "readAt": null,
      "like": false,
      "tag": null,
      "createdAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 15,
    "totalPages": 1
  }
}

5. Get Message Details

GET /api/v1/emails/:id/inbox/:messageId

Retrieves the full details of a specific email message.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Email address ID
`messageId`	string	Yes	Message ID

Success Response (200)

{
  "success": true,
  "data": {
    "id": "msg-123",
    "from": "sender@example.com",
    "to": "test123@ig.do",
    "subject": "Welcome!",
    "text": "Welcome to our service",
    "html": "<p>Welcome to our service</p>",
    "headers": {},
    "readAt": "2026-01-02T13:00:00.000Z",
    "like": false,
    "tag": null,
    "createdAt": "2026-01-02T12:00:00.000Z",
    "updatedAt": "2026-01-02T13:00:00.000Z"
  }
}

Error Responses

404 Not Found - Email address or message not found

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.

Code Examples

cURL - Create Email

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

cURL - List Emails

curl -X GET "https://like.do/api/v1/emails?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript - Get Inbox

const response = await fetch(
  'https://like.do/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox?folder=inbox',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

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

Python - Get Message Details

import requests

url = 'https://like.do/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox/msg-123'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
}

response = requests.get(url, headers=headers)
print(response.json())

Creating API Keys

Navigate to Settings > API Keys in your dashboard
Click Create API Key
Configure your rate limits based on your plan
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
Check quota limits: Monitor your monthly email creation quota
Implement pagination: Use pagination for listing large numbers of emails

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
All timestamps are in ISO 8601 format (UTC)
Folders: inbox (default), starred (liked emails), archive (archived), trash (deleted)

Table of Contents

Email API

Table of Contents