Temp Mail API Documentation - Boomlify

Complete API reference for temporary email service integration

POST`/api/v1/emails/create`

Create a new temporary email address Now supports optional custom_username parameter to create emails with personalized addresses.

Parameters:

custom_username (query, optional): Optional custom username for the email address. Can contain letters, numbers, dots, hyphens, and underscores. Must be 3-30 characters. If omitted, a random username is generated. - Example: john.doe
time (query, optional): Expiration time - Example: permanent
domain (query, optional): Optional custom domain for the email address. Must be a verified domain in your account (use custom_domains endpoint to verify). If not specified, a random public domain is used. - Example: mail.yourdomain.com
create_as_dashboard (query, optional): 💎 Premium Feature - Set to "true" to create a dashboard-style email stored in database with fixed 2-month expiry instead of a time-based API email. Omit or set to "false" for time-based emails (default). Dashboard emails cost 15 credits. Free tier users will receive 403 error. - Example: true

Error Responses:

INVALID_USERNAME (400): Custom username validation failed. Must be 3-30 characters with valid characters only.
EMAIL_IN_USE (409): The custom username is already taken. Choose a different username.
DOMAIN_NOT_FOUND (400): The specified domain does not exist or is not verified. Verify it in your account first.
DOMAIN_NOT_VERIFIED (400): The domain exists but is not yet verified. Complete domain verification first.
DAILY_LIMIT_EXCEEDED (429): You have reached your daily limit for this email type

Auth Required: Yes | Rate Limited: Yes | Group: Quickstart

GET`/api/v1/emails`

List all your active temporary emails

Parameters:

include_expired (query, optional): Include expired emails - Example: true
permanent_only (query, optional): Show only your saved permanent inboxes. Costs 2 credits per request. - Example: true
include_permanent (query, optional): Include your saved permanent inboxes along with recent ones. Costs 2 credits per request. - Example: true
limit (query, optional): Number of emails to return - Example: 50

Error Responses:

INSUFFICIENT_CREDITS (402): Returned when trying to list saved permanent inboxes but account lacks credits.

Auth Required: Yes | Rate Limited: No | Group: Emails

GET`/api/v1/emails/{id}`

Get details of a specific email

Parameters:

id (path, required): Email ID - Example: 550e8400-e29b-41d4-a716-446655440000

Error Responses:

EMAIL_NOT_FOUND (404): Email ID is invalid or email has expired

Auth Required: Yes | Rate Limited: No | Group: Emails

GET`/api/v1/emails/{id}/messages`

Get messages for a specific email

Parameters:

id (path, required): Email ID - Example: 550e8400-e29b-41d4-a716-446655440000
limit (query, optional): Number of messages to return - Example: 50
offset (query, optional): Number of messages to skip - Example: 0

Error Responses:

EMAIL_NOT_FOUND (404): Email ID is invalid or email has expired
INVALID_LIMIT (400): Limit parameter is out of valid range

Auth Required: Yes | Rate Limited: No | Group: Emails

DELETE`/api/v1/emails/{id}`

Delete an email by ID. Supports both time-based API emails (in-memory, immediately deleted) and dashboard emails (database-persisted, immediately deleted). Returns 404 if email not found or already deleted.

Parameters:

id (path, required): Email ID (UUID format). Can be a time-based API email ID or dashboard email ID created with create_as_dashboard=true - Example: 550e8400-e29b-41d4-a716-446655440000

Error Responses:

EMAIL_NOT_FOUND (404): Email does not exist or has already been deleted

Auth Required: Yes | Rate Limited: No | Group: Emails

GET`/api/v1/emails`

💎 Premium Feature - List all emails including dashboard-created emails. This endpoint merges API-created emails with your dashboard emails in a single response. Costs 2 credits per request. Requires Basic plan or higher.

Parameters:

include_dashboard (query, required): Must be set to "true" to access dashboard emails. This enables the premium feature and charges 2 credits. - Example: true
include_expired (query, optional): Include expired emails in the response (both API and dashboard emails) - Example: false
limit (query, optional): Maximum number of emails to return (max: 100) - Example: 50

Error Responses:

TIER_RESTRICTED (403): This is a premium feature. Free tier users cannot access dashboard emails via API.
INSUFFICIENT_CREDITS (402): This operation costs 2 credits. Please add more credits to your account.

Auth Required: Yes | Rate Limited: Yes | Group: Dashboard

GET`/api/v1/emails/{id}`

💎 Premium Feature - Get detailed information about a specific dashboard email. If the email is not found in API store, it searches your dashboard emails. Costs 1 credit per request. Requires Basic plan or higher.

Parameters:

id (path, required): Dashboard email ID (UUID format) - Copy this from your dashboard or from the list-dashboard-emails endpoint - Example: 550e8400-e29b-41d4-a716-446655440000
include_dashboard (query, required): Must be "true" to search dashboard emails. Charges 1 credit. - Example: true

Error Responses:

TIER_RESTRICTED (403): Dashboard email access requires a paid plan
INSUFFICIENT_CREDITS (402): This operation costs 1 credit
EMAIL_NOT_FOUND (404): The requested email was not found or has expired

Auth Required: Yes | Rate Limited: Yes | Group: Dashboard

GET`/api/v1/emails/{id}/messages`

💎 Premium Feature - Retrieve all received messages for a dashboard email with pagination support. Uses cache for fast response times. Costs 1 credit per request. Requires Basic plan or higher.

Parameters:

id (path, required): Dashboard email ID - The UUID of the email you want to fetch messages for - Example: 550e8400-e29b-41d4-a716-446655440000
include_dashboard (query, required): Must be "true" to access dashboard email messages. Charges 1 credit. - Example: true
limit (query, optional): Maximum number of messages to return per page (max: 100) - Example: 20
offset (query, optional): Number of messages to skip for pagination (e.g., offset=20 with limit=20 gets page 2) - Example: 0

Error Responses:

TIER_RESTRICTED (403): Dashboard email access requires a paid plan
INSUFFICIENT_CREDITS (402): This operation costs 1 credit
EMAIL_NOT_FOUND (404): The requested email was not found or has expired

Auth Required: Yes | Rate Limited: Yes | Group: Dashboard

GET`/api/v1/emails/{id}/telegram-forwarding`

Premium Feature - Get Telegram forwarding status for a specific owned mailbox. Supports dashboard mailboxes and permanent API mailboxes. Ownership is checked through the existing cached mailbox lookup paths, and forwarding state is returned from the forwarding cache. Costs 2 credits per request. Requires Basic plan or higher.

Parameters:

id (path, required): Mailbox ID - Use a dashboard mailbox ID or a permanent API mailbox ID whose Telegram forwarding status you want to inspect - Example: 550e8400-e29b-41d4-a716-446655440000
include_dashboard (query, required): Must be set to "true" to access Telegram forwarding mailbox status. Charges 2 credits. - Example: true

Error Responses:

TIER_RESTRICTED (403): This is a premium feature. Free tier users cannot access dashboard email forwarding via API.
INSUFFICIENT_CREDITS (402): This operation costs 2 credits. Please add more credits to your account.
EMAIL_NOT_FOUND (404): The requested mailbox was not found, is unsupported, or has expired

Auth Required: Yes | Rate Limited: Yes | Group: Dashboard

POST`/api/v1/emails/{id}/telegram-forwarding`

Premium Feature - Enable or disable Telegram forwarding for an owned mailbox. Supports dashboard mailboxes and permanent API mailboxes, while reusing the existing forwarding cache and write-through persistence path. Costs 2 credits per request. Requires Basic plan or higher and an active Telegram binding.

Parameters:

id (path, required): Mailbox ID - Use a dashboard mailbox ID or a permanent API mailbox ID whose Telegram forwarding you want to update - Example: 550e8400-e29b-41d4-a716-446655440000
include_dashboard (query, required): Must be set to "true" to update Telegram mailbox forwarding. Charges 2 credits. - Example: true
is_enabled (body, required): Boolean body field. Set true to enable forwarding or false to disable forwarding. - Example: true

Error Responses:

TIER_RESTRICTED (403): This is a premium feature. Free tier users cannot update dashboard email forwarding via API.
INSUFFICIENT_CREDITS (402): This operation costs 2 credits. Please add more credits to your account.
NO_TELEGRAM_BINDING (400): Forwarding cannot be enabled until the account has an active verified Telegram binding.
FORWARDING_LIMIT_EXCEEDED (403): The user has reached the plan limit for active Telegram forwardings.
EMAIL_NOT_FOUND (404): The requested mailbox was not found, is unsupported, or has expired

Auth Required: Yes | Rate Limited: Yes | Group: Dashboard

POST`/api/v1/emails/telegram-forwarding/bulk-enable`

Premium Feature - Bulk enable Telegram forwarding for multiple owned mailboxes in one API request. Supports dashboard mailboxes and permanent API mailboxes, reuses the existing per-email forwarding enable flow, and respects the active-forwarding limit. Costs 2 credits per request. Requires Basic plan or higher and an active Telegram binding.

Parameters:

include_dashboard (query, required): Must be set to "true" to bulk enable Telegram mailbox forwarding. Charges 2 credits. - Example: true
email_ids (body, required): Body field containing a non-empty array of owned mailbox IDs. In the test form, you can enter a single mailbox ID or a JSON array. - Example: ["550e8400-e29b-41d4-a716-446655440000"]

Error Responses:

TIER_RESTRICTED (403): This is a premium feature. Free tier users cannot bulk enable dashboard email forwarding via API.
INSUFFICIENT_CREDITS (402): This operation costs 2 credits total per bulk request.
NO_TELEGRAM_BINDING (400): Forwarding cannot be enabled until the account has an active verified Telegram binding.
FORWARDING_LIMIT_EXCEEDED (403): The user has reached the plan limit for active Telegram forwardings.
EMAIL_NOT_FOUND (404): No matching forwardable mailboxes were found.

Auth Required: Yes | Rate Limited: Yes | Group: Dashboard

POST`/api/v1/emails/create`

💎 Premium Feature - Create a new email with optional custom username. Dashboard emails (create_as_dashboard=true) are stored in DB with fixed 2-month expiry and cost 15 credits. Time-based API emails support custom time options (10min, 1hour, 1day, permanent). Both support custom_username. Requires Basic plan or higher.

Parameters:

create_as_dashboard (query, optional): Set to "true" to create a dashboard-style email stored in database with a fixed 2-month expiry. If omitted, creates a time-based API email in memory. Both support custom_username. - Example: true
custom_username (query, optional): Optional custom username for the email address. Can contain letters, numbers, dots, hyphens, and underscores. Must be 3-30 characters. If omitted, a random username is generated. - Example: john.doe
domain (query, optional): Optional custom domain name for the email address. If not specified, a random public domain will be used. - Example: mail.yourdomain.com

Error Responses:

TIER_RESTRICTED (403): Dashboard email creation requires a paid plan
INSUFFICIENT_CREDITS (402): This operation costs 15 credits
INVALID_USERNAME (400): Custom username validation failed. Must be 3-30 characters with valid characters only.
EMAIL_IN_USE (409): The custom username is already taken. Choose a different username.
INVALID_TIME_PARAMETER (400): Time must be one of: 10min, 1hour, 1day, permanent

Auth Required: Yes | Rate Limited: Yes | Group: Dashboard

GET`/api/v1/account/usage`

Get your API usage statistics

Error Responses:

UNAUTHORIZED (401): API key is required and must be valid

Auth Required: Yes | Rate Limited: No | Group: Account

GET`/api/v1/account/info`

Get your account information

Error Responses:

UNAUTHORIZED (401): API key is required and must be valid

Auth Required: Yes | Rate Limited: No | Group: Account

GET`/api/v1/account/credits`

Get detailed credit balance and usage information

Error Responses:

UNAUTHORIZED (401): API key is required and must be valid

Auth Required: Yes | Rate Limited: No | Group: Account

Temp Mail API Documentation & Testing Hub

Read the docs, test endpoints, and copy code — all on a single page.

Base URL:

https://v1.boomlify.com

Quickstart

Emails

💎 Dashboard API (Premium)

Account

POST /api/v1/emails/create

Create a new temporary email address Now supports optional custom_username parameter to create emails with personalized addresses.

Auth RequiredRate Limited

Documentation

Parameters

query

custom_username

Optional custom username for the email address. Can contain letters, numbers, dots, hyphens, and underscores. Must be 3-30 characters. If omitted, a random username is generated.

Example: john.doe

⚠️ ⚠️ Must be 3-30 characters. Cannot start/end with special characters. Must be unique. Returns 409 if taken.

query

time

Expiration time

Example: permanent

⚠️ Must be one of: 10min, 1hour, 1day, permanent

query

domain

Optional custom domain for the email address. Must be a verified domain in your account (use custom_domains endpoint to verify). If not specified, a random public domain is used.

Example: mail.yourdomain.com

⚠️ ⚠️ Must be a verified custom domain or a public domain. Returns 400 if not available.

query

create_as_dashboard

💎 Premium Feature - Set to "true" to create a dashboard-style email stored in database with fixed 2-month expiry instead of a time-based API email. Omit or set to "false" for time-based emails (default). Dashboard emails cost 15 credits. Free tier users will receive 403 error.

Example: true

⚠️ ⚠️ Must be "true" or omitted. Dashboard emails require Basic plan or higher. Fixed 2-month expiry (time parameter is ignored).

Error Examples

400

INVALID_USERNAME

Username must be at least 3 characters

Custom username validation failed. Must be 3-30 characters with valid characters only.

409

EMAIL_IN_USE

Email address "[email protected]" is already in use

The custom username is already taken. Choose a different username.

400

DOMAIN_NOT_FOUND

Domain "custom.domain" is not available. It must be either a verified custom domain in your account or a public domain.

The specified domain does not exist or is not verified. Verify it in your account first.

400

DOMAIN_NOT_VERIFIED

Custom domain "custom.domain" is not verified. Current status: pending

The domain exists but is not yet verified. Complete domain verification first.

429

DAILY_LIMIT_EXCEEDED

Daily limit exceeded for 1hour emails

You have reached your daily limit for this email type

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

query

include_expired

Include expired emails

Example: true

⚠️ Must be "true" or "false"

query

permanent_only

Show only your saved permanent inboxes. Costs 2 credits per request.

Example: true

⚠️ Must be "true" or "false"

query

include_permanent

Include your saved permanent inboxes along with recent ones. Costs 2 credits per request.

Example: true

⚠️ Must be "true" or "false"

query

limit

Number of emails to return

Example: 50

⚠️ Maximum 100 emails

Error Examples

402

INSUFFICIENT_CREDITS

Add credits to list permanent inboxes.

Returned when trying to list saved permanent inboxes but account lacks credits.

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

pathRequired

Email ID

Example: 550e8400-e29b-41d4-a716-446655440000

⚠️ Must be a valid UUID

Error Examples

404

EMAIL_NOT_FOUND

The requested email was not found or has expired

Email ID is invalid or email has expired

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

pathRequired

Email ID

Example: 550e8400-e29b-41d4-a716-446655440000

⚠️ Must be a valid UUID

query

limit

Number of messages to return

Example: 50

⚠️ Maximum 100 messages

query

offset

Number of messages to skip

Example: 0

⚠️ Must be a non-negative integer

Error Examples

404

EMAIL_NOT_FOUND

The requested email was not found or has expired

Email ID is invalid or email has expired

400

INVALID_LIMIT

Limit must be between 1 and 100

Limit parameter is out of valid range

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

pathRequired

Email ID (UUID format). Can be a time-based API email ID or dashboard email ID created with create_as_dashboard=true

Example: 550e8400-e29b-41d4-a716-446655440000

⚠️ Must be a valid UUID

Error Examples

404

EMAIL_NOT_FOUND

The requested email was not found or has expired

Email does not exist or has already been deleted

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

queryRequired

include_dashboard

Must be set to "true" to access dashboard emails. This enables the premium feature and charges 2 credits.

Example: true

⚠️ Must be "true" - Free tier users will receive a 403 error

query

include_expired

Include expired emails in the response (both API and dashboard emails)

Example: false

query

limit

Maximum number of emails to return (max: 100)

Example: 50

⚠️ Must be between 1 and 100

Error Examples

403

TIER_RESTRICTED

Dashboard email access requires a paid plan (Basic or higher)

This is a premium feature. Free tier users cannot access dashboard emails via API.

402

INSUFFICIENT_CREDITS

Need 2 credits to list dashboard emails

This operation costs 2 credits. Please add more credits to your account.

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

pathRequired

Dashboard email ID (UUID format) - Copy this from your dashboard or from the list-dashboard-emails endpoint

Example: 550e8400-e29b-41d4-a716-446655440000

⚠️ Must be a valid UUID from your dashboard emails

queryRequired

include_dashboard

Must be "true" to search dashboard emails. Charges 1 credit.

Example: true

Error Examples

403

TIER_RESTRICTED

Premium feature

Dashboard email access requires a paid plan

402

INSUFFICIENT_CREDITS

Need 1 credit to access dashboard email

This operation costs 1 credit

404

EMAIL_NOT_FOUND

Email not found

The requested email was not found or has expired

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

pathRequired

Dashboard email ID - The UUID of the email you want to fetch messages for

Example: 550e8400-e29b-41d4-a716-446655440000

⚠️ Must be a valid UUID from your dashboard emails

queryRequired

include_dashboard

Must be "true" to access dashboard email messages. Charges 1 credit.

Example: true

query

limit

Maximum number of messages to return per page (max: 100)

Example: 20

⚠️ Must be between 1 and 100

query

offset

Number of messages to skip for pagination (e.g., offset=20 with limit=20 gets page 2)

Example: 0

⚠️ Must be a non-negative integer

Error Examples

403

TIER_RESTRICTED

Premium feature

Dashboard email access requires a paid plan

402

INSUFFICIENT_CREDITS

Need 1 credit to access dashboard email messages

This operation costs 1 credit

404

EMAIL_NOT_FOUND

Email not found

The requested email was not found or has expired

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

pathRequired

Mailbox ID - Use a dashboard mailbox ID or a permanent API mailbox ID whose Telegram forwarding status you want to inspect

Example: 550e8400-e29b-41d4-a716-446655440000

⚠️ Must be an owned dashboard mailbox ID or permanent API mailbox ID

queryRequired

include_dashboard

Must be set to "true" to access Telegram forwarding mailbox status. Charges 2 credits.

Example: true

⚠️ Must be "true" - Free tier users will receive a 403 error

Error Examples

403

TIER_RESTRICTED

Dashboard email access requires a paid plan (Basic or higher)

This is a premium feature. Free tier users cannot access dashboard email forwarding via API.

402

INSUFFICIENT_CREDITS

Need 2 credits to access dashboard email Telegram forwarding status

This operation costs 2 credits. Please add more credits to your account.

404

EMAIL_NOT_FOUND

Email not found

The requested mailbox was not found, is unsupported, or has expired

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

pathRequired

Mailbox ID - Use a dashboard mailbox ID or a permanent API mailbox ID whose Telegram forwarding you want to update

Example: 550e8400-e29b-41d4-a716-446655440000

⚠️ Must be an owned dashboard mailbox ID or permanent API mailbox ID

queryRequired

include_dashboard

Must be set to "true" to update Telegram mailbox forwarding. Charges 2 credits.

Example: true

⚠️ Must be "true" - Free tier users will receive a 403 error

bodyRequired

is_enabled

Boolean body field. Set true to enable forwarding or false to disable forwarding.

Example: true

⚠️ Must be a boolean value

Error Examples

403

TIER_RESTRICTED

Dashboard email access requires a paid plan (Basic or higher)

This is a premium feature. Free tier users cannot update dashboard email forwarding via API.

402

INSUFFICIENT_CREDITS

Need 2 credits to update dashboard email Telegram forwarding

This operation costs 2 credits. Please add more credits to your account.

400

NO_TELEGRAM_BINDING

No active Telegram binding found. Please bind your Telegram account first.

Forwarding cannot be enabled until the account has an active verified Telegram binding.

403

FORWARDING_LIMIT_EXCEEDED

Forwarding limit exceeded

The user has reached the plan limit for active Telegram forwardings.

404

EMAIL_NOT_FOUND

Email not found

The requested mailbox was not found, is unsupported, or has expired

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

queryRequired

include_dashboard

Must be set to "true" to bulk enable Telegram mailbox forwarding. Charges 2 credits.

Example: true

⚠️ Must be "true" - Free tier users will receive a 403 error

bodyRequired

email_ids

Body field containing a non-empty array of owned mailbox IDs. In the test form, you can enter a single mailbox ID or a JSON array.

Example: ["550e8400-e29b-41d4-a716-446655440000"]

⚠️ Must resolve to a non-empty array of owned dashboard mailbox IDs or permanent API mailbox IDs. The bulk limit is 150 IDs per request.

Error Examples

403

TIER_RESTRICTED

Dashboard email access requires a paid plan (Basic or higher)

This is a premium feature. Free tier users cannot bulk enable dashboard email forwarding via API.

402

INSUFFICIENT_CREDITS

Need 2 credits to bulk enable dashboard email Telegram forwarding

This operation costs 2 credits total per bulk request.

400

NO_TELEGRAM_BINDING

No active Telegram binding found. Please bind your Telegram account first.

Forwarding cannot be enabled until the account has an active verified Telegram binding.

403

FORWARDING_LIMIT_EXCEEDED

Forwarding limit exceeded

The user has reached the plan limit for active Telegram forwardings.

404

EMAIL_NOT_FOUND

Email not found

No matching forwardable mailboxes were found.

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Parameters

query

create_as_dashboard

Set to "true" to create a dashboard-style email stored in database with a fixed 2-month expiry. If omitted, creates a time-based API email in memory. Both support custom_username.

Example: true

⚠️ ⚠️ Dashboard emails cost 15 credits. Fixed 2-month expiry (no time parameter). Free tier users will receive a 403 error. Omit this parameter to create a time-based API email with custom time options.

query

custom_username

Optional custom username for the email address. Can contain letters, numbers, dots, hyphens, and underscores. Must be 3-30 characters. If omitted, a random username is generated.

Example: john.doe

⚠️ ⚠️ Must be 3-30 characters. Cannot start/end with special characters. Must be unique across your emails. If already taken, returns 409 Conflict.

query

domain

Optional custom domain name for the email address. If not specified, a random public domain will be used.

Example: mail.yourdomain.com

⚠️ Must be a verified domain in your account

Error Examples

403

TIER_RESTRICTED

Premium feature

Dashboard email creation requires a paid plan

402

INSUFFICIENT_CREDITS

Need 15 credits to create dashboard email

This operation costs 15 credits

400

INVALID_USERNAME

Username must be at least 3 characters

Custom username validation failed. Must be 3-30 characters with valid characters only.

409

EMAIL_IN_USE

Email address "[email protected]" is already in use

The custom username is already taken. Choose a different username.

400

INVALID_TIME_PARAMETER

Invalid time parameter

Time must be one of: 10min, 1hour, 1day, permanent

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Error Examples

401

UNAUTHORIZED

Invalid or missing API key

API key is required and must be valid

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Error Examples

401

UNAUTHORIZED

Invalid or missing API key

API key is required and must be valid

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Documentation

Error Examples

401

UNAUTHORIZED

Invalid or missing API key

API key is required and must be valid

Example Request

curl -X POST "https://v1.boomlify.com/api/v1/emails/create"

Code Snippets

const response = await fetch("https://v1.boomlify.com/api/v1/emails/create", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

import requests

response = requests.post("https://v1.boomlify.com/api/v1/emails/create", 
  headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
)

data = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://v1.boomlify.com/api/v1/emails/create");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
  "Content-Type": "application/json"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Rate limit: 60 RPMAPI Hub

Test API