MailAPI

API Reference

MailAPI API Reference

Build domains, provision mailboxes, and track queue jobs using MailAPI endpoints.

Authentication & Conventions

Use your API key in the request body for provisioning endpoints, and as query parameters for task result lookups.

Base URL

https://www.mailapi.tech/api

API Key Format

32 characters (alpha-numeric)

Queue Behavior

All create requests are queued and processed asynchronously.

Success Contract

{
    "status": "success"
}

Error Contract

{
    "status": "error",
    "reason": "Error description"
}
GET /api/v1/list/domain?key={key}&caller_id={user_id}

List Domains

Returns all domains for the API key owner account, keyed by domain name.

Query parameter `key` (required API key).

Field Type Required Description
key string(32) Yes Your API key in query string.
caller_id integer Yes Must match the API key owner user ID.

Request Example

curl "{{ url('/api/v1/list/domain') }}?key=YOUR_32_CHARACTER_API_KEY&caller_id=123"

Success Response

{
    "user_id": "123",
    "total_domain": 2,
    "results": {
        "example.com": {
            "status": "verified",
            "domain_quota": "10GB",
            "mailbox_count": "15",
            "created_at": "14-04-2026"
        }
    },
    "status": "success"
}

Error Responses

  • HTTP 401 - Invalid API key.
  • HTTP 403 - Unauthorized caller.

Notes

  • Only domains owned by the API key owner are returned.
  • Mailbox count includes mailboxes under each returned domain.
POST /api/v1/create/domain

Create Domain

Creates a new base domain in your MailAPI workspace and starts provisioning in the background.

Body parameter `key` (required API key).

Field Type Required Description
Domain string Yes Fully qualified domain to create.
Params object No Reserved for optional provisioning metadata.
key string(32) Yes Your API key.

Request Example

curl -X POST "{{ url('/api/v1/create/domain') }}" \
  -H "Content-Type: application/json" \
  -d '{
    "Domain": "example.com",
    "Params": {},
    "key": "YOUR_32_CHARACTER_API_KEY"
  }'

Success Response

{
    "status": "success",
    "domain": "example.com"
}

Error Responses

  • HTTP 401 - Invalid API key.
  • HTTP 409 - Domain already exists for this account.

Notes

  • The domain must not already exist in the tenant account.
  • Provisioning work continues asynchronously after acceptance.
POST /api/v1/create/sub-domain

Create Sub-Domain Batch

Creates up to 10 sub-domains under an existing parent domain in a single queued task.

Body parameter `key` (required API key).

Field Type Required Description
Domain string Yes Existing parent domain owned by your account.
Params.sub_domains string[] Yes List of sub-domain labels, max 10.
key string(32) Yes Your API key.

Request Example

curl -X POST "{{ url('/api/v1/create/sub-domain') }}" \
  -H "Content-Type: application/json" \
  -d '{
    "Domain": "example.com",
    "Params": {
      "sub_domains": ["team", "support", "billing"]
    },
    "key": "YOUR_32_CHARACTER_API_KEY"
  }'

Success Response

{
    "status": "success",
    "domain": "example.com"
}

Error Responses

  • HTTP 404 - Parent domain was not found.
  • HTTP 422 - Maximum 10 sub-domains are allowed per request.
  • HTTP 429 - Sub-domain requests are limited to once per hour for this domain and API key.

Notes

  • Rate limit for successful requests: 1 request/hour per API key + base domain.
  • Sub-domain labels accept letters, numbers, and hyphens.
POST /api/v1/create/mailbox/single

Create Single Mailbox

Queues one mailbox creation request for a domain that belongs to your account.

Body parameter `key` (required API key).

Field Type Required Description
Email_fullname string Yes Mailbox local-part or full mailbox identity payload.
single_bulk string Yes Must be `single`.
Domain string Yes Target domain.
Params object Yes Mailbox creation options.
key string(32) Yes Your API key.

Request Example

curl -X POST "{{ url('/api/v1/create/mailbox/single') }}" \
  -H "Content-Type: application/json" \
  -d '{
    "Email_fullname": "john",
    "single_bulk": "single",
    "Domain": "example.com",
    "Params": {
      "display_name": "John Doe",
      "quota_mb": 1024
    },
    "key": "YOUR_32_CHARACTER_API_KEY"
  }'

Success Response

{
    "status": "success",
    "task_id": 123
}

Error Responses

  • HTTP 401 - Invalid API key.
  • HTTP 404 - Domain not found for this account.

Notes

  • Returns task ID for async status polling.
  • Use Get Single Mailbox Task endpoint to fetch completion result.
POST /api/v1/create/mailbox/bulk

Create Bulk Mailboxes

Queues a bulk mailbox provisioning task and returns a task ID for later retrieval.

Body parameter `key` (required API key).

Field Type Required Description
Email_fullname string Yes Bulk mailbox payload definition.
single_bulk string Yes Must be `bulk`.
Domain string Yes Target domain.
Params object Yes Bulk mailbox provisioning options.
key string(32) Yes Your API key.

Request Example

curl -X POST "{{ url('/api/v1/create/mailbox/bulk') }}" \
  -H "Content-Type: application/json" \
  -d '{
    "Email_fullname": "team",
    "single_bulk": "bulk",
    "Domain": "example.com",
    "Params": {
      "count": 25,
      "quota_mb": 512
    },
    "key": "YOUR_32_CHARACTER_API_KEY"
  }'

Success Response

{
    "status": "success",
    "task_id": 456
}

Error Responses

  • HTTP 401 - Invalid API key.
  • HTTP 404 - Domain not found for this account.

Notes

  • Bulk task processing is asynchronous and queue-backed.
  • Poll the bulk task result endpoint with the returned task ID.
GET /api/v1/list/mailbox?key={key}&caller_id={user_id}&domain={domain}

List Mailboxes

Returns all mailboxes for a specific owned domain, keyed by full email address.

Query parameter `key` (required API key).

Field Type Required Description
key string(32) Yes Your API key in query string.
caller_id integer Yes Must match the API key owner user ID.
domain string Yes Domain to list mailboxes for.

Request Example

curl "{{ url('/api/v1/list/mailbox') }}?key=YOUR_32_CHARACTER_API_KEY&caller_id=123&domain=example.com"

Success Response

{
    "user_id": "123",
    "domain": "example.com",
    "results": {
        "john@example.com": {
            "provisioning_status": "active",
            "mailbox_quota": "1024MB",
            "imap_credentials": null,
            "created_at": "14-04-2026"
        }
    },
    "status": "success"
}

Error Responses

  • HTTP 401 - Invalid API key.
  • HTTP 403 - Unauthorized caller.
  • HTTP 404 - Domain not found for this account.

Notes

  • Only mailboxes owned by the API key owner are returned.
  • Response includes provisioning status and mailbox quota per mailbox.
GET /api/v1/get/mailbox/single?key={key}&task_id={task_id}

Get Single Mailbox Task

Fetches status and final result for a single mailbox provisioning task.

Query parameter `key` (required API key).

Field Type Required Description
key string(32) Yes Your API key in query string.
task_id integer Yes Task identifier returned by create endpoint.

Request Example

curl "{{ url('/api/v1/get/mailbox/single') }}?key=YOUR_32_CHARACTER_API_KEY&task_id=123"

Success Response

{
    "Task_id": 123,
    "total_email": 1,
    "domain": "example.com",
    "results": {
        "john@example.com": {
            "status": "Created successfully."
        }
    },
    "status": "completed",
    "task_id": "123"
}

Error Responses

  • HTTP 404 - Task ID was not found for this API key.
  • HTTP 422 - Task type does not match this endpoint.

Notes

  • If task fails, API responds with error status and failure reason.
  • Response includes both `Task_id` and `task_id` for compatibility.
GET /api/v1/get/mailbox/bulk?key={key}&task_id={task_id}

Get Bulk Mailbox Task

Fetches status and per-mailbox results for a bulk mailbox provisioning task.

Query parameter `key` (required API key).

Field Type Required Description
key string(32) Yes Your API key in query string.
task_id integer Yes Task identifier returned by bulk create endpoint.

Request Example

curl "{{ url('/api/v1/get/mailbox/bulk') }}?key=YOUR_32_CHARACTER_API_KEY&task_id=456"

Success Response

{
    "Task_id": 456,
    "total_email": 25,
    "domain": "example.com",
    "results": {
        "team1@example.com": {
            "status": "Created successfully."
        },
        "team2@example.com": {
            "status": "Created successfully."
        }
    },
    "status": "completed",
    "task_id": "456"
}

Error Responses

  • HTTP 404 - Task ID was not found for this API key.
  • HTTP 422 - Task processing failed.

Notes

  • Endpoint is restricted to tasks created with bulk mailbox workflow.
  • Results include mailbox-by-mailbox status details.