Quick Start

This guide takes you from a new API key to working mailboxes. You will make your first request, choose a workspace, add a domain and create mailboxes on it.

All requests go to https://api.inboxkit.com and send JSON.

Step 1: Get your API key

Go to Settings and open the API & MCP tab.

Under API Keys, click Generate Key, or copy your existing key.

Keep your key private. It gives full access to your account.

Rotate Key creates a new key, and your old key stops working right away. Update every integration that uses it before you rotate.

Step 2: Make your first request

Send your key in the Authorization header as a Bearer token. Get account details does not need a workspace, so it is a good first request.

Response 200

{
  "uid": "3f6c1a2e-0000-4000-8000-000000000001",
  "team": "Example Agency",
  "admin_email": "[email protected]",
  "total_credits": 500,
  "credits_used": 120,
  "credits_remaining": 380,
  "credits_per_google_mailbox": 4,
  "credits_per_ms_outlook_mailbox": 4,
  "subscription_mailbox_slots_google": 100,
  "subscription_mailbox_slots_google_used": 40,
  "subscription_mailbox_slots_google_remaining": 60,
  "subscription_mailbox_slots_ms_outlook": 0,
  "subscription_mailbox_slots_ms_outlook_used": 0,
  "subscription_mailbox_slots_ms_outlook_remaining": 0,
  "subscription_mailbox_slots_total": 100,
  "subscription_mailbox_slots_used": 40,
  "subscription_mailbox_slots_remaining": 60,
  "subscription_mailbox_slots_purchasable": true,
  "current_plan": {
    "name": "Example Plan",
    "uid": "3f6c1a2e-0000-4000-8000-000000000002",
    "cycle": "monthly",
    "pricing": 99,
    "renews_on": "2026-10-26T10:00:00.000Z",
    "purchased_on": "2026-09-26T10:00:00.000Z"
  },
  "auto_topup_enabled": false,
  "auto_topup_config": {
    "mode": "threshold",
    "drops_below": 0,
    "add_credits": 0,
    "forecast_hours": 48
  },
  "webhook_url": null
}

credits_remaining is your wallet balance. The subscription_mailbox_slots_* fields show how many mailboxes your plan still covers. current_plan is null when you have no active plan.

If the key is missing, you get 401:

{
  "code": 401,
  "message": "No auth token"
}

Step 3: Choose a workspace

Domains and mailboxes belong to a workspace. Call List workspaces and copy the uid of the workspace you want to use.

Response 200

{
  "error": false,
  "message": "Workspaces fetched successfully",
  "workspaces": [
    {
      "uid": "8b2d4c6e-0000-4000-8000-000000000010",
      "name": "Example Workspace",
      "webhook_url": "",
      "use_shared_billing": true,
      "workspace_type": "user",
      "created_at": "2026-09-01T09:00:00.000Z",
      "updated_at": "2026-09-01T09:00:00.000Z",
      "domains": 0,
      "assigned_domains": 0,
      "assignable_domains": 0
    }
  ]
}

Send this uid in the X-Workspace-Id header on every domain and mailbox request:

Authorization: Bearer YOUR_API_KEY
X-Workspace-Id: 8b2d4c6e-0000-4000-8000-000000000010
Content-Type: application/json

If an endpoint needs the header and it is missing, you get 400:

{
  "code": 400,
  "message": "Workspace ID is required"
}

If the workspace does not belong to your team, you get 400:

{
  "code": 400,
  "message": "Invalid workspace"
}

Step 4: Set your webhook URL

We recommend doing this before you buy anything. InboxKit then tells your server when a domain or mailbox changes status, so you do not have to poll.

In the dashboard, go to Settings and open the API & MCP tab.

Under Webhooks, enter your endpoint, for example https://your-app.example.com/inboxkit/webhook. Use HTTPS, because mailbox events include login credentials.

Click Save Webhook.

Before you trust an event, verify its signature. See Webhook Integration & Signature Verification.

Step 5: Add a domain

You can buy a new domain through InboxKit or connect one you already own.

Option A: Buy a new domain

First, check that the name is available with Check domain availability. This call does not need X-Workspace-Id.

Response 200

{
  "error": false,
  "message": "Domain is available for registration",
  "banned": false,
  "available": true,
  "registration_price": 12,
  "renewal_price": 14
}

Then buy it with Register domains. With use_wallet_balance: true, the cost is taken from your wallet. domain_forwarding_url is where visitors to the domain are sent.

Response 200

{
  "error": false,
  "message": "Domains registration initiated successfully",
  "domains_count": 1,
  "total_cost": 12,
  "payment_type": "wallet",
  "contact_details": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "organization": "Example Agency",
    "address_line1": "123 Example Street",
    "city": "Springfield",
    "state": "IL",
    "country": "US",
    "postal_code": "62701"
  },
  "domain_uids": ["c1d2e3f4-0000-4000-8000-000000000020"]
}

Save the value in domain_uids. You need it to track the domain.

If your wallet balance is too low, you get 402:

{
  "error": true,
  "message": "Insufficient wallet balance to purchase domains"
}

If you leave out use_wallet_balance, you get a payment link instead. Open url to pay. The domain is registered after the payment goes through.

{
  "error": false,
  "message": "Payment session created successfully",
  "url": "https://checkout.stripe.com/c/pay/cs_live_xxxxxxxxxxxx",
  "session_id": "cs_live_xxxxxxxxxxxx",
  "domains_count": 1,
  "total_cost": 12,
  "domain_uids": ["c1d2e3f4-0000-4000-8000-000000000020"]
}

Option B: Connect a domain you own

Call Get nameservers for domain connection with the domain name. The domain is added to your workspace and you get the nameservers to use.

Response 200

{
  "error": false,
  "message": "Nameservers retrieved successfully",
  "result": [
    {
      "domain": "example.com",
      "nameservers": ["ns1.example.net", "ns2.example.net"],
      "uid": "d4e5f6a7-0000-4000-8000-000000000030",
      "name": "example.com",
      "tld": ".com"
    }
  ]
}

If the domain is already in this workspace, you get 409 with the nameservers it already has:

{
  "error": false,
  "message": "Domain(s) already connected to your workspace: example.com",
  "result": [
    {
      "domain": "example.com",
      "nameservers": ["ns1.example.net", "ns2.example.net"],
      "uid": "d4e5f6a7-0000-4000-8000-000000000030"
    }
  ]
}

Next, log in to the company where you bought the domain and replace its nameservers with the ones in nameservers. Do this soon: if the new nameservers are not picked up within 24 hours, the domain's status changes to expired_propagation and you need fresh nameservers from Regenerate Domain Nameservers.

To see whether the change is visible yet, call Check nameservers propagation:

Response 200

{
  "error": false,
  "message": "Nameservers propagation checked successfully",
  "result": [
    {
      "_id": "000000000000000000000031",
      "name": "example.com",
      "uid": "d4e5f6a7-0000-4000-8000-000000000030",
      "status": "not_connected",
      "createdAt": "2026-09-26T10:00:00.000Z",
      "updatedAt": "2026-09-26T10:00:00.000Z",
      "propagated": false
    }
  ]
}

propagated turns true once the new nameservers are visible.

If your domain is in your own Cloudflare account, you can connect it without changing nameservers. See Connect Cloudflare Domains.

Step 6: Wait until the domain is active

You can only create mailboxes on a domain whose status is active. A new domain goes through a few setup steps first.

With a webhook: wait for a domain.status_changed event where the new status is active.

Without a webhook: call List domains with the domain's uid in uids from time to time and check status.

If you try to buy mailboxes before the domain is active, the request fails with 404:

{
  "error": true,
  "message": "No domains found"
}

Step 7: Create mailboxes

Call Buy mailboxes. Each mailbox needs a name, a username (the part before the @), the domain and the platform.

Response 200

{
  "error": false,
  "message": "Mailbox scheduled to be assigned to domains successfully",
  "mailboxes": [
    {
      "uid": "e7f8a9b0-0000-4000-8000-000000000040",
      "domain_name": "example.org",
      "first_name": "Jane",
      "last_name": "Doe",
      "username": "jane",
      "platform": "GOOGLE",
      "status": "scheduled",
      "renewal_date": null,
      "renewal_cycle": "monthly",
      "createdAt": "2026-09-26T11:00:00.000Z",
      "updatedAt": "2026-09-26T11:00:00.000Z"
    },
    {
      "uid": "e7f8a9b0-0000-4000-8000-000000000041",
      "domain_name": "example.org",
      "first_name": "John",
      "last_name": "Smith",
      "username": "john",
      "platform": "GOOGLE",
      "status": "scheduled",
      "renewal_date": null,
      "renewal_cycle": "monthly",
      "createdAt": "2026-09-26T11:00:00.000Z",
      "updatedAt": "2026-09-26T11:00:00.000Z"
    }
  ]
}

How you pay

Leave out use_wallet_balance to use the mailbox slots on your plan.

Set use_wallet_balance: true to pay from your wallet.

Azure and SMTP mailboxes are always paid from your wallet.

All mailboxes on one domain must use the same platform. See Buy mailboxes for every platform and option.

If your wallet balance is too low, you get 402:

{
  "error": true,
  "message": "Insufficient wallet balance to purchase mailboxes"
}

If you pay with slots and do not have enough free slots, you get 400:

{
  "error": true,
  "message": "Not enough mailbox slots available"
}

Step 8: Wait for the mailboxes and get their credentials

New mailboxes start as scheduled and move to active when they are ready.

With a webhook: wait for a mailbox.status_changed event where the new status is active. The event includes the mailbox credentials.

Without a webhook: call Check mailbox status.

Response 200

{
  "error": false,
  "message": "Mailbox status retrieved successfully",
  "mailboxes": [
    {
      "_id": "000000000000000000000041",
      "uid": "e7f8a9b0-0000-4000-8000-000000000040",
      "first_name": "Jane",
      "last_name": "Doe",
      "username": "jane",
      "platform": "GOOGLE",
      "status": "active",
      "mailbox_update_status": "na",
      "sequencer_status": "na",
      "dns_propagation_status": "propagated",
      "mailbox_reactivation_status": "na",
      "createdAt": "2026-09-26T11:00:00.000Z",
      "updatedAt": "2026-09-26T11:40:00.000Z"
    }
  ]
}

Once a mailbox is active, get its login details with Show mailbox credentials:

Response 200

{
  "error": false,
  "message": "Mailbox credentials retrieved successfully",
  "password": "xxxxxxxxxx",
  "secret": "xxxxxxxxxxxxxxxx",
  "app_password": "xxxxxxxxxxxxxxxx"
}

If the mailbox is not active yet, you get 400:

{
  "error": true,
  "message": "Mailbox is not active yet. Please wait for it to be active."
}

Store these credentials encrypted and never write them to logs.

Want fewer steps?

Place Order buys new domains and creates their mailboxes in a single request.

Next steps

Domain Management: forwarding, DNS, DMARC, renewals and more.

Mailbox Operations: warmup, sequencer export, forwarding and updates.

Deliverability Monitoring: blacklist, bounce and DNS monitoring, and inbox placement tests.

Webhooks: events, retries and signature verification.

Step 1: Get your API key#

Step 2: Make your first request#

Step 3: Choose a workspace#

Step 4: Set your webhook URL#

Step 5: Add a domain#

Option A: Buy a new domain#

Option B: Connect a domain you own#

Step 6: Wait until the domain is active#

Step 7: Create mailboxes#

Step 8: Wait for the mailboxes and get their credentials#

Want fewer steps?#

Next steps#

Step 1: Get your API key

Step 2: Make your first request

Step 3: Choose a workspace

Step 4: Set your webhook URL

Step 5: Add a domain

Option A: Buy a new domain

Option B: Connect a domain you own

Step 6: Wait until the domain is active

Step 7: Create mailboxes

Step 8: Wait for the mailboxes and get their credentials

Want fewer steps?

Next steps