# Premium Inboxes Client API
Premium Inboxes Client API reference. Machine-readable version for LLMs and agents. Human version: https://premiuminboxes.com/api-reference
Base URL: https://api.premiuminboxes.com/api
Welcome to the **Premium Inboxes Client API**. This API lets agencies programmatically manage workspaces, place and cancel orders, and manage email accounts under their account.
---
## Authorization
The Client API uses **API key authentication**. Every request must include a valid API token.
### Token format
- Type: opaque API key (random 32-character alphanumeric string)
- Example: `4hsi40SXVZkyx8sPJablsXX11eAtTf1c`
### How to send the token
Include the token in the **`x-api-token`** header on every request. No prefix (no `Bearer`, no `Basic`):
```
x-api-token: 4hsi40SXVZkyx8sPJablsXX11eAtTf1c
```
### Scope
- One token represents your **agency** (the top-level Premium Inboxes account).
- The token authorizes access to **all workspaces** owned by that agency.
- A specific workspace can be targeted via the optional `x-workspace-id` header on most endpoints.
### How to obtain a token
1. Log in at [https://portal.premiuminboxes.com](https://portal.premiuminboxes.com).
2. Go to **Settings → API Token** and generate one.
3. Store it like a password (env var, secrets manager). Generating a new token immediately invalidates the old one.
### Example request
```bash
curl -X GET "https://api.premiuminboxes.com/api/client/workspaces" \
-H "x-api-token: 4hsi40SXVZkyx8sPJablsXX11eAtTf1c" \
-H "Content-Type: application/json"
```
```js
// Node.js (fetch)
await fetch("https://api.premiuminboxes.com/api/client/workspaces", {
headers: {
"x-api-token": process.env.PI_API_TOKEN,
"Content-Type": "application/json",
},
});
```
### Authentication errors
| Status | Cause |
|--------|-------|
| `401` | `x-api-token` header missing |
| `401` | Token does not match any agency (revoked or invalid) |
| `401` | `x-workspace-id` references a workspace you do not own |
---
## Rate Limiting
### Limit
- **100 requests per minute**, counted per `x-api-token`.
### Response when limited
When the limit is exceeded, the API responds with:
```
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
```
```json
{
"name": "TooManyRequestsError",
"message": "Rate limit exceeded. Please check the RateLimit-* and Retry-After response headers and retry after the indicated period."
}
```
### Rate limit headers
Every response includes these headers so clients can pace themselves:
| Header | Meaning |
|--------|---------|
| `RateLimit-Limit` | Maximum requests allowed in the current window (`100`) |
| `RateLimit-Remaining` | Requests remaining in the current window |
| `RateLimit-Reset` | Seconds until the window resets |
| `Retry-After` | (only on 429) Seconds to wait before retrying |
## Workspaces
### GET /client/workspaces - List workspaces
Response 200:
```json
{
"workspaces": [
{
"id": "string",
"name": "string",
"status": "active",
"hasActiveSubscriptions": true
}
]
}
```
Example:
```bash
curl -X GET "https://api.premiuminboxes.com/api/client/workspaces" \
-H "x-api-token: YOUR_API_KEY"
```
### POST /client/workspaces - Create workspace
Request body (application/json):
```json
{
"name": "string",
"copyPaymentMethod": true,
"copyBillingDetails": true,
"copyPlatformSettings": true
}
```
Response 200:
```json
{
"workspace": {
"id": "string",
"name": "string",
"status": "active",
"hasActiveSubscriptions": true
}
}
```
Example:
```bash
curl -X POST "https://api.premiuminboxes.com/api/client/workspaces" \
-H "x-api-token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"string","copyPaymentMethod":true,"copyBillingDetails":true,"copyPlatformSettings":true}'
```
### GET /client/workspaces/{workspaceId} - Single workspace
Parameters:
- workspaceId (in: path, type: string, required: yes)
Response 200:
```json
{
"workspace": {
"id": "string",
"name": "string",
"status": "active",
"hasActiveSubscriptions": true
}
}
```
Example:
```bash
curl -X GET "https://api.premiuminboxes.com/api/client/workspaces/{workspaceId}" \
-H "x-api-token: YOUR_API_KEY"
```
## Subscriptions
### GET /client/subscription - Get subscriptions
Parameters:
- x-workspace-id (in: header, type: string, required: no)
Response 200:
```json
{
"data": [
{
"orders": [
{
"user": "string",
"client": "string",
"placedBy": "string",
"airtableId": "string",
"supabaseId": "string",
"status": "Received & Data Validation",
"flowStartedAt": {},
"profilePictureLink": "string",
"fullName": "string",
"forwardedDomain": "string",
"domains": [
null
],
"prefixVariants": [
null
],
"issues": [
null
],
"inboxes": {
"total": null,
"perDomain": null
},
"emails": [
null
],
"tags": [
null
],
"additionalInfo": "string",
"emailProvider": "Google",
"_id": "string",
"createdAt": "string",
"updatedAt": "string"
}
],
"tags": [
{
"user": "string",
"client": "string",
"name": "string",
"color": "string",
"_id": "string"
}
],
"workspaceId": "string",
"workspaceName": "string",
"workspaceAlias": "string",
"user": "string",
"client": "string",
"chargebeeId": "string",
"status": "Future",
"lastBillingDate": {},
"nextBillingDate": {},
"items": [
{
"id": "string",
"type": "plan",
"quantity": 0,
"unitPrice": 0,
"price": 0
}
],
"discount": 0,
"price": 0,
"cancelled": {
"date": {},
"reason": "string"
},
"_id": "string"
}
]
}
```
Example:
```bash
curl -X GET "https://api.premiuminboxes.com/api/client/subscription" \
-H "x-api-token: YOUR_API_KEY"
```
### GET /client/subscription/{subscriptionId} - Single subscription
Parameters:
- subscriptionId (in: path, type: string, required: yes)
Response 200:
```json
{
"user": "string",
"client": "string",
"orders": [
"string"
],
"chargebeeId": "string",
"status": "Future",
"lastBillingDate": {},
"nextBillingDate": {},
"items": [
{
"id": "string",
"type": "plan",
"quantity": 0,
"unitPrice": 0,
"price": 0
}
],
"discount": 0,
"price": 0,
"cancelled": {
"date": {},
"reason": "string"
},
"tags": [
"string"
],
"_id": "string"
}
```
Example:
```bash
curl -X GET "https://api.premiuminboxes.com/api/client/subscription/{subscriptionId}" \
-H "x-api-token: YOUR_API_KEY"
```
### PUT /client/subscription/cancel/{subscriptionId} - Cancel subscription
Parameters:
- subscriptionId (in: path, type: string, required: yes)
Request body (application/json):
```json
{
"reason": "string",
"removeImmediately": true
}
```
Response 200:
```json
null
```
Example:
```bash
curl -X PUT "https://api.premiuminboxes.com/api/client/subscription/cancel/{subscriptionId}" \
-H "x-api-token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"string","removeImmediately":true}'
```
### PUT /client/subscription/reactivate/{subscriptionId} - Reactivate subscription
Parameters:
- subscriptionId (in: path, type: string, required: yes)
Response 200:
```json
null
```
Example:
```bash
curl -X PUT "https://api.premiuminboxes.com/api/client/subscription/reactivate/{subscriptionId}" \
-H "x-api-token: YOUR_API_KEY"
```
## Purchase
### POST /client/purchase - Create a purchase order (long-running, ~30-45s)
**This request typically takes 30-45 seconds to complete.**
Parameters:
- x-workspace-id (in: header, type: string, required: no)
Request body (application/json):
```json
{
"emailProvider": "Google",
"hosting": {
"platform": "Cloudflare",
"username": "string",
"password": "string",
"namecheapAccessTutorial": "Yes - I reviewed the tutorial and am submitting the access information in requested format.",
"namecheapBackupCodes": "string",
"goDaddyAccessTutorial": "Yes - I sent DELEGATE ACCESS to [email protected] and entered my GoDaddy Account Name (NOT email) below.",
"goDaddyAccountName": "string",
"porkbunAccessTutorial": "Yes - I disabled all 3 2FAs AND the \"Unrecognized Device 2FA\"."
},
"forwardedDomain": "string",
"domains": "string",
"sequencer": {
"platform": "Smartlead",
"username": "string",
"password": "string",
"bisonUrl": "string",
"bisonWorkspaceName": "string",
"workspaceName": "string",
"enableWarmup": true
},
"numberOfInboxes": 0,
"inboxesPerDomain": 0,
"prefixVariants": [
"string"
],
"emailFirstName": "string",
"emailLastName": "string",
"password": "string",
"profilePictureLink": "string",
"masterInboxEmail": "string",
"additionalInfo": "string",
"coupon": "string",
"personas": [
{
"firstName": "string",
"lastName": "string",
"domain": "string",
"prefixVariants": [
"string"
],
"password": "string",
"profilePictureLink": "string",
"masterInboxEmail": "string",
"forwardedDomain": "string",
"hosting": {
"platform": "Cloudflare",
"username": "string",
"password": "string",
"namecheapAccessTutorial": "Yes - I reviewed the tutorial and am submitting the access information in requested format.",
"namecheapBackupCodes": "string",
"goDaddyAccessTutorial": "Yes - I sent DELEGATE ACCESS to [email protected] and entered my GoDaddy Account Name (NOT email) below.",
"goDaddyAccountName": "string",
"porkbunAccessTutorial": "Yes - I disabled all 3 2FAs AND the \"Unrecognized Device 2FA\"."
},
"sequencer": {
"platform": "Smartlead",
"username": "string",
"password": "string",
"bisonUrl": "string",
"bisonWorkspaceName": "string",
"workspaceName": "string",
"enableWarmup": true
},
"hostingPlatformUrl": "string",
"sequencerPlatformUrl": "string",
"hosting2fa": "string",
"csvSeqTags": "string"
}
],
"manualPersonas": [
{
"firstName": "string",
"lastName": "string",
"domains": [
"string"
],
"prefixVariants": [
"string"
]
}
],
"insured": true,
"flowStartedAt": 0
}
```
Response 200:
```json
"string"
```
Example:
```bash
curl -X POST "https://api.premiuminboxes.com/api/client/purchase" \
-H "x-api-token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"emailProvider":"Google","hosting":{"platform":"Cloudflare","username":"string","password":"string","namecheapAccessTutorial":"Yes - I reviewed the tutorial and am submitting the access information in requested format.","namecheapBackupCodes":"string","goDaddyAccessTutorial":"Yes - I sent DELEGATE ACCESS to [email protected] and entered my GoDaddy Account Name (NOT email) below.","goDaddyAccountName":"string","porkbunAccessTutorial":"Yes - I disabled all 3 2FAs AND the \"Unrecognized Device 2FA\"."},"forwardedDomain":"string","domains":"string","sequencer":{"platform":"Smartlead","username":"string","password":"string","bisonUrl":"string","bisonWorkspaceName":"string","workspaceName":"string","enableWarmup":true},"numberOfInboxes":0,"inboxesPerDomain":0,"prefixVariants":["string"],"emailFirstName":"string","emailLastName":"string","password":"string","profilePictureLink":"string","masterInboxEmail":"string","additionalInfo":"string","coupon":"string","personas":[{"firstName":"string","lastName":"string","domain":"string","prefixVariants":["string"],"password":"string","profilePictureLink":"string","masterInboxEmail":"string","forwardedDomain":"string","hosting":{"platform":"Cloudflare","username":"string","password":"string","namecheapAccessTutorial":"Yes - I reviewed the tutorial and am submitting the access information in requested format.","namecheapBackupCodes":"string","goDaddyAccessTutorial":"Yes - I sent DELEGATE ACCESS to [email protected] and entered my GoDaddy Account Name (NOT email) below.","goDaddyAccountName":"string","porkbunAccessTutorial":"Yes - I disabled all 3 2FAs AND the \"Unrecognized Device 2FA\"."},"sequencer":{"platform":"Smartlead","username":"string","password":"string","bisonUrl":"string","bisonWorkspaceName":"string","workspaceName":"string","enableWarmup":true},"hostingPlatformUrl":"string","sequencerPlatformUrl":"string","hosting2fa":"string","csvSeqTags":"string"}],"manualPersonas":[{"firstName":"string","lastName":"string","domains":["string"],"prefixVariants":["string"]}],"insured":true,"flowStartedAt":0}'
```
## Orders
### GET /client/order - Get orders
Parameters:
- x-workspace-id (in: header, type: string, required: no)
Response 200:
```json
{
"data": [
{
"subscriptionStatus": "Future",
"subscriptionId": "string",
"subscriptionPrice": 0,
"tags": [
{
"user": "string",
"client": "string",
"name": "string",
"color": "string",
"_id": "string"
}
],
"workspaceId": "string",
"workspaceName": "string",
"workspaceAlias": "string",
"user": "string",
"client": "string",
"placedBy": "string",
"airtableId": "string",
"supabaseId": "string",
"status": "Received & Data Validation",
"flowStartedAt": {},
"profilePictureLink": "string",
"fullName": "string",
"forwardedDomain": "string",
"domains": [
"string"
],
"prefixVariants": [
"string"
],
"issues": [
{
"reason": "string"
}
],
"inboxes": {
"total": 0,
"perDomain": 0
},
"emails": [
{
"firstName": "string",
"lastName": "string",
"email": "string",
"password": "string",
"status": "active"
}
],
"additionalInfo": "string",
"emailProvider": "Google",
"_id": "string",
"createdAt": "string",
"updatedAt": "string"
}
]
}
```
Example:
```bash
curl -X GET "https://api.premiuminboxes.com/api/client/order" \
-H "x-api-token: YOUR_API_KEY"
```
### GET /client/order/{orderId} - Single order
Parameters:
- orderId (in: path, type: string, required: yes)
Response 200:
```json
{
"subscription": "string",
"items": [
{
"id": "string",
"type": "plan",
"quantity": 0,
"unitPrice": 0,
"price": 0
}
],
"discount": 0,
"subscriptionStatus": "Future",
"personas": [
{
"id": "string",
"firstName": "string",
"lastName": "string",
"domain": "string",
"prefixVariants": [
"string"
],
"type": "string"
}
],
"workspaceId": "string",
"workspaceName": "string",
"workspaceAlias": "string",
"_id": "string",
"createdAt": "string",
"updatedAt": "string",
"user": "string",
"client": "string",
"placedBy": "string",
"airtableId": "string",
"supabaseId": "string",
"status": "Received & Data Validation",
"flowStartedAt": {},
"profilePictureLink": "string",
"fullName": "string",
"forwardedDomain": "string",
"domains": [
"string"
],
"prefixVariants": [
"string"
],
"issues": [
{
"reason": "string"
}
],
"inboxes": {
"total": 0,
"perDomain": 0
},
"emails": [
{
"firstName": "string",
"lastName": "string",
"email": "string",
"password": "string",
"status": "active"
}
],
"tags": [
"string"
],
"additionalInfo": "string",
"emailProvider": "Google"
}
```
Example:
```bash
curl -X GET "https://api.premiuminboxes.com/api/client/order/{orderId}" \
-H "x-api-token: YOUR_API_KEY"
```
## Email Accounts
### GET /client/email-account - List email accounts
Parameters:
- x-workspace-id (in: header, type: string, required: no)
Response 200:
```json
{
"emailAccounts": [
{
"orderId": "string",
"workspaceId": "string",
"workspaceName": "string",
"email": "string",
"domain": "string",
"status": "string",
"createdAt": "string"
}
]
}
```
Example:
```bash
curl -X GET "https://api.premiuminboxes.com/api/client/email-account" \
-H "x-api-token: YOUR_API_KEY"
```
### POST /client/email-account/cancel - Cancel emails
Parameters:
- x-workspace-id (in: header, type: string, required: no)
Request body (application/json):
```json
{
"emails": [
{
"orderId": "string",
"email": "string",
"domain": "string"
}
]
}
```
Response 200:
```json
{
"cancelledCount": 0,
"cancelledEmails": [
"string"
]
}
```
Example:
```bash
curl -X POST "https://api.premiuminboxes.com/api/client/email-account/cancel" \
-H "x-api-token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"emails":[{"orderId":"string","email":"string","domain":"string"}]}'
```
