Getting Started

This guide walks through the fastest path from signup to a working domain, mailbox, and first API call. Follow the steps below (sub-domains are optional), then use the links at the bottom to go deeper.

• check_circleCreate a MailAPI account.
• check_circleOpen Settings → API Keys in your dashboard after login.
• check_circleGenerate an API key; It already has all permissions you need:
• check_circleStore the 32-character key securely.
• check_circleSend it via Authorization: Bearer <key> or X-Api-Key.

Full REST reference: API docs

Create a root domain with the API (write permission required):

curl --fail-with-body --silent --show-error \
  -X POST "$APP_URL/api/v1/create/domain" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Domain": "example.com",
    "Params": {
      "total_mailbox_allowed": 100
    }
  }'

The response includes task_id. Poll until status is completed (read permission):

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_KEY" \
  "$APP_URL/api/v1/get/domain?task_id=$TASK_ID"

When complete, the response includes DNS records (MX, TXT verification, mail-host A). Add them at your DNS host, then verify in the dashboard.

Skip this step if you only need mailboxes on the root domain (for example, john@example.com).

After the parent domain is provisioned, create sub-domains in batches of up to 10 labels:

curl --fail-with-body --silent --show-error \
  -X POST "$APP_URL/api/v1/create/sub-domain" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Domain": "example.com",
    "Params": {
      "sub_domains": ["team", "support", "billing"]
    }
  }'

Poll the task until status is completed:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_KEY" \
  "$APP_URL/api/v1/get/sub-domain?task_id=$TASK_ID"

When complete, publish the returned MX records for each sub-domain hostname (for example, team.example.com). Sub-domains typically require MX verification only. See DNS verification for details.

Set Domain to the target hostname (root domain or sub-domain FQDN). Params.email_id must belong to that hostname.

Single mailbox example:

curl --fail-with-body --silent --show-error \
  -X POST "$APP_URL/api/v1/create/mailbox/single" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Email_fullname": "John Doe",
    "single_bulk": "single",
    "Domain": "example.com",
    "Params": {
      "email_id": "john@example.com",
      "password": 0
    }
  }'

Use numeric 0 for password to auto-generate a secure password (string "0" is rejected). Poll for credentials:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_KEY" \
  "$APP_URL/api/v1/get/mailbox/single?task_id=$TASK_ID"

Bulk mailbox example:

curl --fail-with-body --silent --show-error \
  -X POST "$APP_URL/api/v1/create/mailbox/bulk" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Email_fullname": "Team Member",
    "single_bulk": "bulk",
    "Domain": "example.com",
    "Params": {
      "mailbox_no": 25,
      "password": 0
    }
  }'

Poll bulk results with GET /api/v1/get/mailbox/bulk?task_id=$TASK_ID.

• check_circleInbound HTTP: POST /api/v1/mail/inbound (requires inbound permission). See the API reference.
• check_circleInbox retrieval: GET /api/v1/emails, GET /api/v1/emails/sync, and related endpoints (requires read).
• check_circleWebhooks: POST /api/v1/webhooks with url and events (email.received, email.read, email.deleted; requires webhook permission). See Webhooks.