API Introduction
Welcome to the Mailin.ai API! This document provides everything you need to start interacting with our
services programmatically. All API endpoints are prefixed with /api/v1/public/.
Authentication
Obtain an API Token
Send a POST request to the login endpoint with your
credentials to obtain a bearer token.
Request Body
| Parameter | Type | Description |
|---|---|---|
| string | Required. Your registered user email address. | |
| password | string | Required. Your account password. |
| device_name | string | Required. A unique name for your application. |
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "your-secure-password",
"device_name": "My-Awesome-App"
}'
Example Success Response (200 OK)
{
"user_id": 1,
"token": "1|LPQJJwsJTM3mEu49zYfhyFQszC7ZLgPyBHEJsDiO7aa1980c"
}Error Responses
Our API uses standard and custom HTTP status codes. A `404 Not Found` error is returned for mismatched IDs or dubious ownership to protect user privacy. For other errors, see below.
| Code | Meaning | Description |
|---|---|---|
| 210 | Accepted | The request has been received and has begun processing. |
| 310 | API Communication Error | Error communicating with another API. You may try again. |
| 311 | Request Refused | The request cannot be completed because the data was not prepared. |
| 312 | Subscription Required | You do not have an active subscription. |
| 313 | Incomplete Action | An error occurred mid-process; some parts may be incomplete. |
| 401 | Unauthorized | No valid API token was provided. |
| 422 | Unprocessable Entity | The request syntax is correct but contains semantic errors (e.g., validation failed). |
Documentation Help
Get Documentation
Endpoint for retrieving general API information.
API Endpoints
User Management
Endpoint for retrieving your account information. Note: you can only fetch the data for the authenticated user.
Get User Details
Retrieve the account details for the currently authenticated user.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {user_id} | integer | Required. The ID of the user. Must match the authenticated user's ID. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Success Response (200 OK)
{
"id": 1,
"username": "johndoe",
"phone_no": "1-800-555-0199",
"first_name": "John",
"last_name": "Doe",
"email_verified_at": "2023-10-26T10:00:00.000000Z",
"email": "user@example.com",
"org_name": "ACME Corporation",
"country_name": "United States",
"city_name": "Anytown",
"address": "123 Main St",
"postal_code": "12345",
"region": "CA",
"country_code": "US",
"country_code_name": "USA",
"mailboxes_slots": 50,
"created_at": "2023-10-26T09:30:00.000000Z"
}Server Management
Endpoints for retrieving information about your provisioned servers.
List All Servers
Retrieve a list of all virtual machine servers associated with your account.
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Success Response (200 OK)
[
{
"id": 201,
"public_ip": "192.0.2.1",
"hostname": "vm-inbound-01.mailin.ai",
"state": "Running",
"active": 1,
"server_type": "inbound"
},
{
"id": 202,
"public_ip": "198.51.100.5",
"hostname": "vm-outbound-01.mailin.ai",
"state": "Stopped",
"active": 0,
"server_type": "outbound"
}
]Get a Single Server
Retrieve detailed information for a specific server by its ID.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {server_id} | integer | Required. The ID of the server. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Success Response (200 OK)
{
"id": 201,
"public_ip": "192.0.2.1",
"hostname": "vm-inbound-01.mailin.ai",
"state": "Running",
"active": 1,
"server_type": "inbound"
}SMTP Domain Management
Endpoints for managing, purchasing, and retrieving information about your domains.
Transfer Inboxkit Domain
Transfer an existing domain to your account. This is an
asynchronous process. You will receive a status code of 200 if the request is
accepted for processing.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_name | string | Required. The domain name to transfer (e.g., "mybusiness.com"). |
| uid | string | Required. Domain uid (e.g., "11c236de-c2e5-4797-bb73-73d861dc40fb"). |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/transfer/inboxkit
-H "Authorization: Bearer YOUR_API_TOKEN"
-H "Content-Type: application/json"
-d '{
"domain_name": "mybusiness.com",
"uid": "11c236de-c2e5-4797-bb73-73d861dc40fb"
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and the transfer process has been started.",
"domain_id": "123"
}Example Error Response (422 Unprocessable Entity)
{
"message": "Domain already exists in your account."
}List All Inboxkit Domains
Retrieve a paginated list of all domains associated with your account.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| page | integer | The page number to retrieve. Default is 1.
|
| per_page | integer | Number of items per page. Default is 15.
|
| name | string | Filter domains by name using wildcard search. Example:
example will match example.com and
myexample.co.
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/domains/get/inboxkit-domains?page=1&per_page=10&name=example" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 1,
"name": "example.com",
"status": "1",
"domain_provider": "inboxkit",
"created_at": "2023-10-27T10:00:00.000000Z",
"updated_at": "2023-10-27T10:00:00.000000Z"
},
{
"id": 2,
"name": "example.co",
"status": "0",
"domain_provider": "inboxkit",
"created_at": "2023-10-28T12:30:00.000000Z",
"updated_at": "2023-10-28T12:30:00.000000Z"
}
],
"first_page_url": "https://api.mailin.ai/api/v1/public/domains?page=1",
"from": 1,
"last_page": 5,
"last_page_url": "https://api.mailin.ai/api/v1/public/domains?page=5",
"next_page_url": "https://api.mailin.ai/api/v1/public/domains?page=2",
"path": "https://api.mailin.ai/api/v1/public/domains",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 50
}List All Domains
Retrieve a paginated list of all domains associated with your account.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| page | integer | The page number to retrieve. Default is 1.
|
| per_page | integer | Number of items per page. Default is 15.
|
| name | string | Filter domains by name using wildcard search. Example:
example will match example.com and
myexample.co.
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/domains?page=1&per_page=10&name=example" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 1,
"name": "example.com",
"main_domain": "example.com",
"name_servers": "ns1.mailin.ai, ns2.mailin.ai",
"name_server_status": "1",
"status": "1",
"domain_provider": "dynadot",
"created_at": "2023-10-27T10:00:00.000000Z",
"updated_at": "2023-10-27T10:00:00.000000Z"
},
{
"id": 2,
"name": "example.co",
"main_domain": "example.com",
"name_servers": null,
"name_server_status": "0",
"status": "0",
"domain_provider": "godaddy",
"created_at": "2023-10-28T12:30:00.000000Z",
"updated_at": "2023-10-28T12:30:00.000000Z"
}
],
"first_page_url": "https://api.mailin.ai/api/v1/public/domains?page=1",
"from": 1,
"last_page": 5,
"last_page_url": "https://api.mailin.ai/api/v1/public/domains?page=5",
"next_page_url": "https://api.mailin.ai/api/v1/public/domains?page=2",
"path": "https://api.mailin.ai/api/v1/public/domains",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 50
}Get a Single Domain
Retrieve detailed information for a specific domain by its ID.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {domain_id} | integer | Required. The ID of the domain. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Success Response (200 OK)
{
"id": 1,
"name": "example.com",
"main_domain": 1,
"name_servers": "ns1.mailin.ai, ns2.mailin.ai",
"name_server_status": "Active",
"status": "Active",
"provider_type": "string",
"domain_provider": "dynadot",
"created_at": "2023-10-27T10:00:00.000000Z",
"updated_at": "2023-10-27T10:00:00.000000Z"
}
Check Domain Availability
Check whether a domain name is available for purchase. The API
will return 200 OK if the domain is available and 404 Not Found if
unavailable.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| domain_name | string | Required. The domain name to check (e.g., "mynewbusiness.com"). |
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/domains/check/domain-availability?domain_name=mynewbusiness.com"
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"available": true,
"message": "Domain is available"
}Example Error Response (404 Not Found)
{
"available": false,
"message": "Domain is unavailable"
}Buy a Domain
Purchase a new domain. This is an asynchronous process. You will
receive a status code of 210 if the request is accepted for processing.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_name | string | Required. The domain name to purchase (e.g., "newdomain.com"). Allowed TLDs: .com, .co, .ca, .biz. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/buy \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain_name": "mynewbusiness.com"
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and will be processed as soon as possible.",
"uuid" : "5d297ac4-1bf4-4f3c-935c-ec9df38d63b3"
}Example Error Response (422 Unprocessable Entity)
{
"message": "The requested domain(s) are unavailable.",
"unavailable": {
"domain": "mynewbusiness.com"
}
}Add Sub Domain
Request Body
| Parameter | Type | Description |
|---|---|---|
| subdomain | string | Required. Prefix of the subdomain to create (e.g., "sales"). |
| domain | string | Required. The parent domain under which this subdomain will be added (e.g., "getopener.com"). Must be active. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/add/subdomain
-H "Authorization: Bearer YOUR_API_TOKEN"
-H "Content-Type: application/json"
-d '{
"subdomain": "sales",
"domain": "getopener.com"
}'Example Success Response (201 Created)
{
"message": "Your request has been received and will be processed as soon as possible."
}Example Error Responses (422 Unprocessable Entity)
{
"message": "The specified domain 'getopener.com' does not exist or is not active."
}
{
"message": "Subdomain already exists."
}Buy Multiple Domains
Purchase multiple new domains in a single request. This is an asynchronous process.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_names | array | Required. An array of domain names to purchase. Allowed TLDs: .com, .co, .ca, .biz. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/buy-multiple \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain_names": [
"mynewbusiness.com",
"anothergreatidea.co"
]
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and will be processed as soon as possible."
"uuid" : "5d297ac4-1bf4-4f3c-935c-ec9df38d63b3"
}Example Error Response (422 Unprocessable Entity)
{
"message": "The requested domain(s) are unavailable.",
"unavailable": [
"mynewbusiness.com",
"anothergreatidea.co"
]
}Transfer a Domain
Transfer an existing domain to your account. This is an
asynchronous process. You will receive a status code of 200 if the request is
accepted for processing.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_name | string | Required. The domain name to transfer (e.g., "mybusiness.com"). |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/transfer
-H "Authorization: Bearer YOUR_API_TOKEN"
-H "Content-Type: application/json"
-d '{
"domain_name": "mybusiness.com"
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and the transfer process has been started.",
"name_servers": [
"ns-123.awsdns-45.com",
"ns-234.awsdns-56.net",
"ns-345.awsdns-67.org",
"ns-456.awsdns-78.co.uk"
]
}Get Domain Job Status
Retrieve the current status and details of a domain creation batch job.
Use the job_id returned when initiating the job.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| job_id | integer | Required. The unique ID of the domain creation. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/domains/status/5d297ac4-1bf4-4f3c-935c-ec9df38d63b3" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"id": 5d297ac4-1bf4-4f3c-935c-ec9df38d63b3,
"status": "pending",
"report": "Job Created - BatchAddDomain pending",
"data": [
"10",
"11",
"12"
]
}Example Error Response (404 Not Found)
{
"message": "Domain not found."
}Delete a Domain
Permanently delete a domain and all of its associated mailboxes from the system. This action cannot be undone.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {domain_id} | integer | Required. The ID of the domain to delete. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Success Response (200 OK)
{
"message": "Domain and related mailboxes has been removed."
}Get Domain Rate Limit
Retrieve the current sending rate limit for a specific domain.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {domain_id} | integer | Required. The ID of the domain. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Success Response (200 OK)
{
"id": 1,
"name": "example.com",
"rate_limit": "500 / d"
}Forward a Domain
Forward an existing domain to another domain. You will receive a status code of
200 upon successful.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_id | integer | Required. The ID of the domain. |
| forward_to | string | Required. The destination domain where the domain will be forwarded (e.g., "mynewbusiness.com"). |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/forward \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain_id": 1234,
"forward_to": "mynewbusiness.com"
}'Example Success Response (200 OK)
{
"message": "Domain forwarding has been successfully updated."
}Remove Domain Forwarding
Remove forwarding from an existing domain. You will receive a status code of
200 upon success.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_id | integer | Required. The ID of the domain for which forwarding should be removed. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/remove/forward \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain_id": 1234
}'Example Success Response (200 OK)
{
"message": "Domain forwarding has been successfully removed."
}Forward Email
Set up email forwarding for a domain. You will receive a status code of 200
upon successful update.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_id | integer | Required. The ID of the domain. |
| forward_to | string | Required. The destination email address where incoming emails will be forwarded (e.g., "user@example.com"). |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/email/forward \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain_id": 1234,
"forward_to": "user@example.com"
}'Example Success Response (200 OK)
{
"message": "Email forwarding has been successfully updated."
}SMTP Mailbox Management
Endpoints for creating, viewing, and managing individual mailboxes within your domains.
List All Mailboxes
Retrieve a list of all mailboxes associated with your account, with optional filtering by name.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (default: 1). |
| per_page | integer | Number of results per page (default: 15). |
| name | string |
Filter mailboxes by name query parameter.
The search will match both the mailbox name and the username (email
address) using wildcard search.
Example: john matches John Doe or
john.doe@example.com.
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/mailboxes?name=john.doe@example.com&per_page=10" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 101,
"domain_id": 1,
"name": "John Doe",
"username": "john.doe@example.com",
"password": "password",
"redirect_email": null,
"status": "Active",
"rate_limit": "50",
"imap_host": "mail.example.com",
"imap_port": 993,
"smtp_host": "mail.example.com",
"smtp_port": 465,
"created_at": "2023-10-27T11:00:00.000000Z",
"updated_at": "2023-10-27T11:00:00.000000Z"
},
{
"id": 102,
"domain_id": 1,
"name": "Jane Doe",
"username": "jane.doe@example.com",
"password": "password",
"redirect_email": null,
"status": "Active",
"rate_limit": "50",
"imap_host": "mail.example.com",
"imap_port": 993,
"smtp_host": "mail.example.com",
"smtp_port": 465,
"created_at": "2023-10-27T11:00:00.000000Z",
"updated_at": "2023-10-27T11:00:00.000000Z"
}
],
"first_page_url": "https://api.mailin.ai/api/v1/public/mailboxes?page=1&name=john",
"from": 1,
"last_page": 1,
"last_page_url": "https://api.mailin.ai/api/v1/public/mailboxes?page=1&name=john",
"next_page_url": null,
"path": "https://api.mailin.ai/api/v1/public/mailboxes",
"per_page": 10,
"prev_page_url": null,
"to": 2,
"total": 2
}
Get a Single Mailbox
Retrieve detailed information for a specific mailbox by its ID.
Authorization
Requires a valid Bearer Token in the Authorization header.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Example Success Response (200 OK)
{
"id": 101,
"domain_id": 1,
"name": "John Doe",
"username": "john.doe@example.com",
"password": "encrypted_password_value",
"redirect_email": null,
"status": "Active",
"rate_limit": "500 / 1h",
"created_at": "2023-10-27T11:00:00.000000Z",
"updated_at": "2023-10-27T11:00:00.000000Z"
}Create Mailboxes
Create one or more new mailboxes by providing an array of
mailbox objects. This is an asynchronous process. A status code of 210
indicates the request was accepted for processing.
Request Body
| Parameter | Type | Description |
|---|---|---|
| mailboxes | array | Required. An array of mailbox objects to create. Must contain at least one object. |
| ↳ username | string | Required. The full email address for the mailbox (e.g., "sales@example.com"). |
| ↳ name | string | Required. The display name for the mailbox (e.g., "Sales Team"). |
| ↳ password | string | Optional. A password for the mailbox. Must be 8-24 characters. If not provided, a secure password will be generated. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mailboxes": [
{
"username": "sales@example.com",
"name": "Sales Team",
"password": "a-very-secure-password"
},
{
"username": "info@example.com",
"name": "Info Desk",
"password": "a-very-secure-password"
}
]
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and will be processed as soon as possible.",
"uuid" : "5d297ac4-1bf4-4f3c-935c-ec9df38d63b3"
}Get Mailbox Job Status
Retrieve the current status and details of a mailbox creation batch job.
Use the job_id returned when initiating the job.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| job_id | integer | Required. The unique ID of the mailbox creation. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/mailboxes/status/5d297ac4-1bf4-4f3c-935c-ec9df38d63b3" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"id": "5d297ac4-1bf4-4f3c-935c-ec9df38d63b3",
"status": "pending",
"report": "Job Created - BatchAddMailboxes pending",
"data": [
{
"id": 3,
"domain_id": 107,
"name": "Marketing Team",
"username": "outreach@example.biz",
"password": "Password",
"redirect_email": null,
"status": "1",
"rate_limit": null,
"imap_host": "mail.example.biz",
"imap_port": 993,
"smtp_host": "mail.example.biz",
"smtp_port": 465,
"created_at": "2025-10-24T06:42:55.000000Z",
"updated_at": "2025-10-24T06:42:56.000000Z"
}
]
}
Example Error Response (404 Not Found)
{
"message": "Mailbox not found."
}Update Mailbox Name
Update the display name for a specific mailbox.
Request Body
| Parameter | Type | Description |
|---|---|---|
| name | string | Required. The new display name for the mailbox. |
Authorization
Requires a valid Bearer Token in the Authorization header.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/{mailbox_id}/name \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe"
}'Example Success Response (200 OK)
{
'message' => 'Mailbox name has been updated.'
}Update Mailbox Password
Update the password for a specific mailbox.
Request Body
| Parameter | Type | Description |
|---|---|---|
| password | string | Required. The new password. Must be at least 8 characters. |
Authorization
Requires a valid Bearer Token in the Authorization header.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/{mailbox_id}/password \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"password": "newP@SS1234"
}'Example Success Response (200 OK)
{
'message' => 'Mailbox password has been updated.'
}Delete a Mailbox
Permanently delete a mailbox. This action cannot be undone.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox to delete. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Success Response (200 OK)
{
"message": "Mailbox removed."
}Get Mailbox Rate Limit
Retrieve the current sending rate limit for a specific mailbox.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Success Response (200 OK)
{
"id": 101,
"username": "john.doe@example.com",
"rate_limit": "500 / 1h"
}Google Domain Management
Endpoints for managing, purchasing, and retrieving information about your domains.
List All Domains
Retrieve a paginated list of all domains associated with your account.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| page | integer | The page number to retrieve. Default is 1.
|
| per_page | integer | Number of items per page. Default is 15.
|
| name | string | Filter domains by name using wildcard search. Example:
example will match example.com and
myexample.co.
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/domains/list/google?page=1&per_page=10&name=example" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 1,
"name": "example.com",
"main_domain": "example.com",
"name_servers": "ns1.mailin.ai, ns2.mailin.ai",
"name_server_status": "1",
"status": "1",
"domain_provider": "dynadot",
"provider_type": "google",
"created_at": "2023-10-27T10:00:00.000000Z",
"updated_at": "2023-10-27T10:00:00.000000Z"
},
{
"id": 2,
"name": "example.co",
"main_domain": "example.com",
"name_servers": null,
"name_server_status": "0",
"status": "0",
"domain_provider": "godaddy",
"provider_type": "google",
"created_at": "2023-10-28T12:30:00.000000Z",
"updated_at": "2023-10-28T12:30:00.000000Z"
}
],
"first_page_url": "https://api.mailin.ai/api/v1/public/domains/list/google?page=1",
"from": 1,
"last_page": 5,
"last_page_url": "https://api.mailin.ai/api/v1/public/domains/list/google?page=5",
"next_page_url": "https://api.mailin.ai/api/v1/public/domains/list/google?page=2",
"path": "https://api.mailin.ai/api/v1/public/domains/list/google",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 50
}Buy a Domain
Purchase a new domain. This is an asynchronous process. You will
receive a status code of 210 if the request is accepted for processing.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_name | string | Required. The domain name to purchase (e.g., "newdomain.com"). Allowed TLDs: .com, .co, .ca, .biz. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/buy/google \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain_name": "mynewbusiness.com"
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and will be processed as soon as possible.",
"uuid" : "5d297ac4-1bf4-4f3c-935c-ec9df38d63b3"
}Example Error Response (422 Unprocessable Entity)
{
"message": "The requested domain(s) are unavailable.",
"unavailable": {
"domain": "mynewbusiness.com"
}
}Buy Multiple Domains
Purchase multiple new domains in a single request. This is an asynchronous process.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_names | array | Required. An array of domain names to purchase. Allowed TLDs: .com, .co, .ca, .biz. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/buy-multiple/google \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain_names": [
"mynewbusiness.com",
"anothergreatidea.co"
]
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and will be processed as soon as possible."
"uuid" : "5d297ac4-1bf4-4f3c-935c-ec9df38d63b3"
}Example Error Response (422 Unprocessable Entity)
{
"message": "The requested domain(s) are unavailable.",
"unavailable": [
"mynewbusiness.com",
"anothergreatidea.co"
]
}Transfer a Domain
Transfer an existing domain to your account. This is an
asynchronous process. You will receive a status code of 200 if the request is
accepted for processing.
Request Body
| Parameter | Type | Description |
|---|---|---|
| domain_name | string | Required. The domain name to transfer (e.g., "mybusiness.com"). |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/domains/transfer/google
-H "Authorization: Bearer YOUR_API_TOKEN"
-H "Content-Type: application/json"
-d '{
"domain_name": "mybusiness.com"
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and the transfer process has been started.",
"name_servers": [
"ns-123.awsdns-45.com",
"ns-234.awsdns-56.net",
"ns-345.awsdns-67.org",
"ns-456.awsdns-78.co.uk"
]
}Google Mailbox Management
Endpoints for creating, viewing, and managing individual mailboxes within your domains.
List All Mailboxes
Retrieve a list of all mailboxes associated with your account, with optional filtering by name.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (default: 1). |
| per_page | integer | Number of results per page (default: 15). |
| name | string |
Filter mailboxes by name query parameter.
The search will match both the mailbox name and the username (email
address) using wildcard search.
Example: john matches John Doe or
john.doe@example.com.
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/mailboxes/list/google?name=john.doe@example.com&per_page=10" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 101,
"domain_id": 1,
"name": "John Doe",
"username": "john.doe@example.com",
"password": "password",
"signature": "Best regards, John Doe",
"redirect_email": null,
"status": "1",
"provider_type": "google",
"created_at": "2023-10-27T11:00:00.000000Z",
"updated_at": "2023-10-27T11:00:00.000000Z"
},
{
"id": 102,
"domain_id": 1,
"name": "Jane Doe",
"username": "jane.doe@example.com",
"password": "password",
"signature": "Best regards, John Doe",
"redirect_email": null,
"status": "1",
"provider_type": "google",
"created_at": "2023-10-27T11:00:00.000000Z",
"updated_at": "2023-10-27T11:00:00.000000Z"
}
],
"first_page_url": "https://api.mailin.ai/api/v1/public/mailboxes/list/google?page=1&name=john",
"from": 1,
"last_page": 1,
"last_page_url": "https://api.mailin.ai/api/v1/public/mailboxes/list/google?page=1&name=john",
"next_page_url": null,
"path": "https://api.mailin.ai/api/v1/public/mailboxes/list/google",
"per_page": 10,
"prev_page_url": null,
"to": 2,
"total": 2
}
Get a Single Mailbox
Retrieve detailed information for a specific mailbox by its ID.
Authorization
Requires a valid Bearer Token in the Authorization header.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Example Success Response (200 OK)
{
"id": 101,
"domain_id": 1,
"name": "John Doe",
"username": "john.doe@example.com",
"password": "password_value",
"signature": "Best regards, John Doe",
"redirect_email": null,
"status": "1",
"provider_type": "google",
"created_at": "2023-10-27T11:00:00.000000Z",
"updated_at": "2023-10-27T11:00:00.000000Z"
}Create Mailboxes
Create one or more new mailboxes by providing an array of
mailbox objects. This is an asynchronous process. A status code of 210
indicates the request was accepted for processing.
Request Body
| Parameter | Type | Description |
|---|---|---|
| mailboxes | array | Required. An array of mailbox objects to create. Must contain at least one object. |
| ↳ username | string | Required. The full email address for the mailbox (e.g., "john.doe@example.com"). |
| ↳ first_name | string | Required. The display fist name for the mailbox (e.g., "John"). |
| ↳ last_name | string | Required. The display last name for the mailbox (e.g., "Doe"). |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/add/google \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mailboxes": [
{
"username": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe"
},
{
"username": "john.steeve@example.com",
"first_name": "John",
"last_name": "Steeve"
}
]
}'Example Success Response (210 Accepted)
{
"message": "Your request has been received and will be processed as soon as possible.",
"uuid" : "5d297ac4-1bf4-4f3c-935c-ec9df38d63b3"
}Get Mailbox Job Status
Retrieve the current status and details of a mailbox creation batch job.
Use the job_id returned when initiating the job.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| job_id | integer | Required. The unique ID of the mailbox creation. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/mailboxes/status/5d297ac4-1bf4-4f3c-935c-ec9df38d63b3" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"id": "5d297ac4-1bf4-4f3c-935c-ec9df38d63b3",
"status": "pending",
"report": "Job Created - BatchAddMailboxes pending",
"data": [
{
"id": 3,
"domain_id": 107,
"name": "Marketing Team",
"username": "outreach@example.biz",
"signature": "Best regards, John Doe",
"password": "Password",
"redirect_email": null,
"status": "1",
"provider_type": "google",
"created_at": "2025-10-24T06:42:55.000000Z",
"updated_at": "2025-10-24T06:42:56.000000Z"
}
]
}
Example Error Response (404 Not Found)
{
"message": "Mailbox not found."
}Update Mailbox Name
Update the display name for a specific mailbox.
Request Body
| Parameter | Type | Description |
|---|---|---|
| name | string | Required. The new display name for the mailbox. |
Authorization
Requires a valid Bearer Token in the Authorization header.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/{mailbox_id}/name \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe"
}'Example Success Response (200 OK)
{
'message' => 'Mailbox name has been updated.'
}Generate Mailbox TOTP
Generate a Time-based One-Time Password (TOTP) for a Google mailbox.
This action is allowed only for mailboxes connected with the google provider.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Authorization
Requires a valid Bearer Token in the Authorization header.
The mailbox must belong to the authenticated user.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/123/generate-totp \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"error": false,
"message": "Mailbox TOTP generated successfully",
"totp": "700221",
"expires_at": 1770360450
}Show Mailbox Credentials
Retrieve mailbox credentials for a Google mailbox. Only available for mailboxes
connected with the google provider.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Authorization
Requires a valid Bearer Token.
Example Request
curl -X GET https://api.mailin.ai/api/v1/public/mailboxes/123/show-credentials \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Success Response (200 OK)
{
"error": false,
"message": "Mailbox credentials retrieved successfully",
"password": "R9yAvvm9UN",
"secret": "dmaptyzdjhbkhhrzot2nvr4hjk7tk3mg",
"app_password": "uphw yazt rfrf dmmw "
}Add Mailbox Signature
Add an email signature to a Google mailbox.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Request Body
| Parameter | Type | Description |
|---|---|---|
| signature | string | Required. Mailbox signature text. |
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/123/add-signature \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"signature": "Best regards,\nJohn Doe"
}'
Success Response (200 OK)
{
"message": "Signatures processed successfully",
}Delete Mailbox Signature
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Example Request
curl -X DELETE https://api.mailin.ai/api/v1/public/mailboxes/123/delete-signature \
-H "Authorization: Bearer YOUR_API_TOKEN"
Success Response
{
"message": "Signatures removed successfully",
}Setup Mailbox Forwarding
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Request Body
| Parameter | Type | Description |
|---|---|---|
| forwarding_email | Required. Forwarding email address. |
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/123/forwarding/setup \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"forwarding_email": "forward@example.com"
}'
Success Response
{
"message": "Forwardng processed successfully",
}Update Mailbox Forwarding
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Request Body
| Parameter | Type | Description |
|---|---|---|
| forwarding_email | Required. Forwarding email address. |
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/123/forwarding/update \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"forwarding_email": "updated@example.com"
}'
Success Response
{
"message": "Forwardng update processed successfully",
}Remove Mailbox Forwarding
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| {mailbox_id} | integer | Required. The ID of the mailbox. |
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/mailboxes/123/google/forwarding \
-H "Authorization: Bearer YOUR_API_TOKEN"
Success Response
{
"message": "Forwardng remove processed successfully",
}Microsoft Management
Manage inbox providers, registrars, and other related services under your account.
Add Inbox Provider
Create a new inbox provider for your account.
Request Body
| Parameter | Type | Description |
|---|---|---|
| name | string | Display name of the provider. |
| provider | string | Provider type. Allowed: reachinbox, plusvibe, instantly, manyreach, smartlead. |
| api_key | string | API key for the provider (if required). |
| oauth_url | string | OAuth URL for authentication (required for some providers). |
| username | string | Username/email for the provider (if required). |
| password | string | Password for the provider (if required). |
| workspace_id | string | Workspace ID (for providers like PlusVibe). |
Example Request
curl -X POST "https://api.mailin.ai/api/v1/public/inbox-providers/add" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "SmartLead Account",
"provider": "smartlead",
"api_key": "xxxx",
"oauth_url": "https://smartlead.example.com/oauth"
}'Example Success Response (201 Created)
{
"message": "Provider has been successfully created.",
"provider_id": 1
}Inbox Provider List
Retrieve a paginated list of all inbox providers for your account.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| per_page | integer | Number of results per page (default: 15). |
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/inbox-providers?per_page=10" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 1,
"user_id": 5,
"name": "SmartLead Account",
"provider": "smartlead",
"api_key": "xxxxxx",
"oauth_url": "https://smartlead.example.com/oauth",
"username": null,
"workspace_id": null
}
],
"first_page_url": "https://api.mailin.ai/api/v1/public/inbox-providers?page=1",
"from": 1,
"last_page": 5,
"last_page_url": "https://api.mailin.ai/api/v1/public/inbox-providers?page=5",
"next_page_url": "https://api.mailin.ai/api/v1/public/inbox-providers?page=2",
"path": "https://api.mailin.ai/api/v1/public/inbox-providers",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 50
}Update Inbox Provider
Update the details of an existing inbox provider.
Request Body
| Parameter | Type | Description |
|---|---|---|
| provider | string | Provider type (reachinbox, plusvibe, instantly, manyreach, smartlead). |
| api_key | string | API key (if required). |
| oauth_url | string | OAuth URL (if required). |
| username | string | Username/email (if required). |
| password | string | Password (if required). |
| workspace_id | string | Workspace ID (for PlusVibe). |
Example Request
curl -X PUT "https://api.mailin.ai/api/v1/public/inbox-providers/update/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"provider": "smartlead",
"api_key": "updated_key",
"oauth_url": "https://smartlead.example.com/oauth"
}'Example Success Response (200 OK)
{
"message": "Provider updated successfully."
}Remove Inbox Provider
Delete an existing inbox provider from your account.
Example Request
curl -X DELETE "https://api.mailin.ai/api/v1/public/inbox-providers/delete/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" Example Success Response (200 OK)
{
"message": "Provider deleted successfully."
} Add Domain Registrar
Create a new domain registrar for your account.
Request Body
| Parameter | Type | Description |
|---|---|---|
| name | string | Registrar display name. |
| provider | string | Provider type. Allowed: porkbun, namecheap, godaddy, spaceship. |
| api_key | string | API key for the registrar. |
| secret_api_key | string | Secret API key (if required). |
| api_user | string | API user (for Namecheap). |
| username | string | Username/email (for Namecheap). |
| whitelisted_ip | string |
Please whitelist the following server IPs in your Namecheap account:
65.109.237.170 44.206.212.194 Go to: Namecheap → Profile → Tools → API Access Add both IPs under "Whitelisted IPs". |
| customer_id | string | Customer ID (optional). Required only if you are using a GoDaddy reseller account. |
Example Request
curl -X POST "https://api.mailin.ai/api/v1/public/domain-registrars/add" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My GoDaddy Account",
"provider": "godaddy",
"api_key": "xxxx",
"secret_api_key": "xxxx",
"customer_id": "123456"
}' Example Success Response (201 Created)
{
"message": "Domain registrar created successfully.",
"id": 1
}Domain Registrar List
Retrieve a paginated list of all domain registrars associated with your account.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| per_page | integer | Number of results per page (default: 10). |
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/domain-registrars?per_page=10" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 1,
"user_id": 5,
"name": "My GoDaddy Account",
"provider": "godaddy",
"api_key": "xxxx",
"username": "user@example.com"
}
],
"first_page_url": "https://api.mailin.ai/api/v1/public/domain-registrars?page=1",
"from": 1,
"last_page": 5,
"last_page_url": "https://api.mailin.ai/api/v1/public/domain-registrars?page=5",
"next_page_url": "https://api.mailin.ai/api/v1/public/domain-registrars?page=2",
"path": "https://api.mailin.ai/api/v1/public/domain-registrars",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 50
}Update Domain Registrar
Update details of an existing domain registrar.
Request Body
| Parameter | Type | Description |
|---|---|---|
| provider | string | Provider type. Allowed: porkbun, namecheap, godaddy, spaceship. |
| api_key | string | API key for the registrar. |
| secret_api_key | string | Secret API key (if required). |
| api_user | string | API user (for Namecheap). |
| username | string | Username/email (for Namecheap). |
| whitelisted_ip | string | Whitelisted IP (for Namecheap, must be valid IP). |
| customer_id | string | Optional customer ID (for GoDaddy). |
Example Request
curl -X PUT "https://api.mailin.ai/api/v1/public/domain-registrars/update/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"provider": "godaddy",
"api_key": "updated_key",
"secret_api_key": "updated_secret"
}'Example Success Response (200 OK)
{
"message": "Registrar updated successfully."
}Remove Domain Registrar
Delete an existing domain registrar from your account.
Example Request
curl -X DELETE "https://api.mailin.ai/api/v1/public/domain-registrars/1" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"message": "Registrar deleted successfully."
}Add Azure Order
Create a new Azure order by specifying domain, provider, and mailbox configuration (auto or manual).
Request Body
| Parameter | Type | Description |
|---|---|---|
| mailbox_mode | string |
auto = system generates mailboxes manual = user provides mailboxes |
| full_name | array | Required when mailbox_mode = auto |
| mailboxes | array (100) | Required when mailbox_mode = manual |
| mailboxes[].name | string | Mailbox user name |
| mailboxes[].email | string | Email must belong to given domain |
| domain | string | For purchase: must end with .com, .co, .biz, .ca |
| is_purchase | integer | 1 = purchase, 0 = transfer |
| provider_id | integer | Inbox Provider ID |
| domain_registrar_id | integer | Domain Registrar ID |
Mailbox Logic
- Auto: System generates 100 mailboxes
- Manual: User must send exactly 100 mailboxes
- Emails must match the domain
Example Request (Auto Mode)
curl -X POST "https://api.mailin.ai/api/v1/public/azure-orders/add" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mailbox_mode": "auto",
"full_name": ["John Doe","Sam Doe"],
"domain": "example.com",
"is_purchase": 1,
"provider_id": 1
}'Example Request (Manual Mode)
curl -X POST "https://api.mailin.ai/api/v1/public/azure-orders/add" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mailbox_mode": "manual",
"mailboxes": [
{
"name": "John Doe",
"email": "john@example.com"
}
// total 100 entries
],
"domain": "example.com",
"is_purchase": 1,
"provider_id": 1
}'Example Success Response (201 Created)
{
"message": "Order processed successfully. You can check the order status using the status API endpoint."
}Example Error Response
{
"message": "Order already exists in your account."
}Azure Orders List
Retrieve a paginated list of all Azure orders along with associated provider, registrar, and mailboxes.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| per_page | integer | Number of results per page (default: 10) |
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/azure-orders?per_page=10" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 4,
"user_id": 2,
"full_name": ["Tomer Levi"],
"domain": "example.com",
"mailbox_mode": "auto",
"provider_id": 1,
"domain_registrar_id": 1,
"is_purchase": 0,
"created_at": "2026-02-12T12:36:01.000000Z",
"updated_at": "2026-03-25T06:51:05.000000Z",
"provider": null,
"registrar": null,
"mailboxes": [
{
"name": "John Doe",
"username": "john@example.com",
"password": "******"
}
]
}
],
"per_page": 10,
"total": 1
}Get Nameservers
Fetch generated nameservers for the domain.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/azure-orders/nameservers/1" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Response
{
"status": "ready",
"nameservers": [
"ns1.example.com",
"ns2.example.com"
]
}
Get Order Status
Check whether the Azure order is ready or still in progress.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/azure-orders/status/1" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Response
{
"data": {
"id": 1,
"status": "ready"
}
}
Get Mailboxes
Retrieve all mailboxes associated with an Azure order.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/azure-orders/get-mailboxes/1" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Response
{
"mailboxes": [
{
"name": "John Doe",
"username": "john@example.com",
"password": "******"
}
]
}
Delete Azure Order
Delete an Azure order and its associated domain.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/azure-orders/remove/1" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Response
{
"message": "Order deleted successfully."
}
Set Master Domain
Set forwarding domain for the Azure order.
Request Body
| Parameter | Type | Description |
|---|---|---|
| forward_to | string | Domain emails will be forwarded (e.g. example.com). |
Example Request
curl -X POST "https://api.mailin.ai/api/v1/public/azure-orders/set-redirect-domain/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"forward_to": "example.com",
}'Response
{
"message": "Master domain set successfully."
}
Sets the inbox provider for the order.
Request Body
| Parameter | Type | Description |
|---|---|---|
| provider_id | integer | Inbox provider ID. |
Example Request
curl -X POST "https://api.mailin.ai/api/v1/public/azure-orders/set-inbox-provider/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"provider_id": 1,
}'Response
{
"message": "Inbox Provider set successfully."
}
Remove the assigned inbox provider from the Azure order.
Example Request
curl -X POST "https://api.mailin.ai/api/v1/public/azure-orders/remove-inbox-provider/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
Response
{
"message": "Inbox Provider removed successfully."
}
Trigger Reupload
Example Request
curl -X POST "https://api.mailin.ai/api/v1/public/azure-orders/trigger-re-upload/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
Response
{
"message": "Reupload triggered successfully."
}
Get Inbox Provider Upload Status
Fetch the current upload status summary for an Azure inbox provider order.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/azure-orders/get-inbox-provider-status/4" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"
Example Success Response (200 OK)
{
"upload_status_summary": {
"total": 100,
"uploaded": 0,
"alreadyExistsOtherAccount": 0,
"pending": 100,
"failed": 0
}
}Email Verification Management
Endpoints for verifying single email addresses and retrieving their verification status. Use these APIs to check whether an email is valid, risky, or undeliverable.
Verify Single Email
Start verification of a single email address. This is an asynchronous process.
Use the Get Single Email endpoint to check the final status of the
verification.
Request Body
| Parameter | Type | Description |
|---|---|---|
| string | Required. The email address to be verified (e.g.,
test@example.com).
|
|
| type | string |
Required. Verification type. Possible values:
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/verify-single-email \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"type": "standard"
}'Example Success Response (210 Accepted)
{
"message": "Verification complete.",
"task_id": "abc12345",
"email": "test@example.com",
"status": "success",
"score": 95,
"result": "deliverable",
"credit_used": 1
}Get Single Email Detail
Retrieve the status and result of a single email verification task.
Use the task_id returned from Verify Single Email.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| task_id | string | Required. The unique task ID of the verification request. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/get-single-email?task_id=abc12345" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"task_id": "abc12345",
"email": "test@example.com",
"status": "verifying",
"result": null,
"score": null,
"credits_used": 1
}Verify Bulk Email File
Upload a file containing multiple email addresses for bulk verification.
The verification process runs asynchronously. Use the task_id from the response
to check the status of the verification.
Request Body
| Parameter | Type | Description |
|---|---|---|
| file | file (csv, xlsx) | Required. File containing email addresses. Maximum size: 25 MB. |
| type | string |
Required. Verification type. Possible values:
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/verify-bulk-file \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "file=@/path/to/emails.csv" \
-F "type=standard"Example Success Response (210 Accepted)
{
"message": "Your file has been uploaded and verification has started.",
"task_id": "bulk_123456"
}Example Error Response (422 Unprocessable Entity)
{
"message": "You need 500 credits to verify this file, but you only have 200."
}Verify Bulk Emails (Comma-Separated)
Submit multiple email addresses (comma-separated string) for bulk verification.
Maximum 500 emails per request are allowed.
The verification process runs asynchronously. Use the task_id from the response
to check the status of the verification.
Request Body
| Parameter | Type | Description |
|---|---|---|
| emails | string |
Required. Comma-separated list of email addresses to verify.
Maximum 500 emails in a single request.
Example: "test1@example.com,test2@example.com"
|
| type | string |
Required. Verification type. Possible values:
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/verify-bulk-emails \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "emails=test1@example.com,test2@example.com,test3@example.com" \
-F "type=standard"Example Success Response (210 Accepted)
{
"message": "Your verification has started and is currently in progress.",
"task_id": "bulk_123456"
}Example Error Response (422 Unprocessable Entity)
{
"message": "You cannot verify more than 500 emails at once."
}Get Bulk Verification Task Detail
Retrieve detailed results for a bulk email verification task using its task_id.
This endpoint provides counts of deliverable, risky, catch-all, undeliverable, and unknown
emails.
If the verification is still running, the API will return a pending status message.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| task_id | string | Required. The unique task ID returned when the file was uploaded for verification. |
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/get-task-detail?task_id=bulk_123456" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Response (When Verification Still Running)
{
"message": "Email verification is still in progress. Please check the status after some time."
}Example Response (Task Failed & Refund Issued)
{
"message": "Your task could not be processed. The used credits have been refunded to your account.",
"reason": "Column with email addresses not found"
}
Example Response (Catch-All Verification Finished)
{
"task_id": "bulk_123456",
"created_at": "2025-08-20 12:45:22",
"total_rows": 1200,
"status": "finished",
"deliverable": 950,
"catch_all": 100,
"risky": 50,
"undeliverable": 80,
"unknown": 20
}Example Response (Standard Verification Finished)
{
"task_id": "bulk_123456",
"created_at": "2025-08-20 10:15:09",
"total_rows": 500,
"status": "finished",
"deliverable": 420,
"catch_all": 30,
"invalid": 25,
"unknown": 20,
"duplicate": 5
}Credit History
Retrieve the authenticated user's credit transaction history. This includes credit additions, deductions, and the remaining total after each transaction. Results are returned in paginated format.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| per_page | integer |
Optional. Number of records per page.
Default: 15.
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/credit-history?per_page=10" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"current_page": 1,
"data": [
{
"id": 12,
"reason": "Bulk verification started",
"credit": 0,
"debit": 50,
"total_credit": 450
},
{
"id": 11,
"reason": "Purchased credits",
"credit": 500,
"debit": 0,
"total_credit": 500
}
],
"first_page_url": "https://api.mailin.ai/api/v1/public/credit-history?page=1",
"from": 1,
"last_page": 3,
"last_page_url": "https://api.mailin.ai/api/v1/public/credit-history?page=3",
"links": [...],
"next_page_url": "https://api.mailin.ai/api/v1/public/credit-history?page=2",
"path": "https://api.mailin.ai/api/v1/public/credit-history",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 25
}Get Credits
Retrieve the total available credits for the authenticated user account.
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X GET "https://api.mailin.ai/api/v1/public/get-credits" \
-H "Authorization: Bearer YOUR_API_TOKEN"Example Success Response (200 OK)
{
"total_credits": 120000
}Download Verified Emails
Download the results of a completed bulk email verification task.
This endpoint generates a downloadable CSV file (for standard type)
or a direct download link (for catch_all type).
Only finished/completed tasks can be downloaded.
Request Body
| Parameter | Type | Description |
|---|---|---|
| task_id | string | Required. The task ID received when the bulk verification was initiated. |
| download_type | string |
Required. Determines which results to download.
Possible values depend on the verification type:
|
Authorization
Requires a valid Bearer Token in the Authorization header.
Example Request
curl -X POST https://api.mailin.ai/api/v1/public/download-verified-emails \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "task_id=bulk_123456" \
-F "download_type=deliverable"Example Success Response (200 OK)
{
"download_url": "https://api.mailin.ai/storage/tmp/result-bulk_123456-1693456789.csv"
}Example Response (When Verification Still Running)
{
"message": "Task is still in progress. Please try downloading once it is finished."
}