> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-Accounts API

> Create sub-accounts, update profiles, configure sending limits and status, and manage agency settings.

Sub-accounts separate client sending under a parent account. Access requires an eligible active plan; unavailable features return `403` with `feature_not_available_for_active_plan`. Check your [plan](/docs/account/plans-billing.md) before provisioning.

## Authentication

**Base URL:** `https://pro.api.serversmtp.com/api/v2`

Send the parent account's `consumerKey` and `consumerSecret` headers with **Statistics & Management APIs** (`APIS`) permission. Its IP restrictions must allow your server. See [authentication](/docs/api-reference/authentication.md).

## Dashboard setup

The **Sub Accounts** creation wizard has four steps:

1. Enter the email, a password set by the parent, and profile details.
2. Select a sending IP already assigned to the parent.
3. Review domain verification instructions.
4. Confirm the details and click **Create**.

Set sending credits from the sub-account list after creation. Create a Consumer Key and Consumer Secret for the new sub-account before sending. New sub-accounts do not receive a key automatically. SMTP credentials are the sub-account's Consumer Key and Consumer Secret.

## List sub-accounts

```bash Terminal theme={"system"}
curl --get 'https://pro.api.serversmtp.com/api/v2/subaccounts/list' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10'
```

`GET /subaccounts/list` accepts these optional query parameters:

| Parameter | Description |
| - | - |
| `page`, `limit` | Positive integers; defaults `1` and `10`. |
| `filterByEmail` | Full or partial email address. |
| `filterByActive` | `true` or `false`. |
| `filterByIP[]` or `filterByIP` | IPv4 addresses. Repeat `filterByIP[]` for each address, or pass one `filterByIP` value or a comma-separated list. IPv6 addresses return `400` with `ip_should_be_IPV4_format`. |
| `orderby` | `email` (default) or `last_used`. |
| `ordertype` | `asc` or `desc`. |

The response is `{count, results}`. Each result includes `subaccount_id`, `parent_id`, `email`, `ip`, `active`, `limit`, `sent`, `last_used`, `plan_expiration`, `plan_limit_interval`, and `expired`. Use `subaccount_id` in the paths below.

## Check an email address

`GET /subaccounts/email-exists` checks whether an email is already associated with a turboSMTP account. The query name is case-sensitive: use capital `Email`.

```bash Terminal theme={"system"}
curl --get 'https://pro.api.serversmtp.com/api/v2/subaccounts/email-exists' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  --data-urlencode 'Email=client@example.com'
```

Example response:

```json theme={"system"}
{"result": false}
```

## Create a sub-account

`POST /subaccounts` requires `email`, `password`, `confirm_password`, `first_name`, `last_name`, `ip`, and `policy_agree: true`.

Choose a password with at least 10 characters, an uppercase letter, a lowercase letter, and a digit. Both password fields must match. Replace the example password and IP; the IP must already belong to the parent account.

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/subaccounts' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "client@example.com",
    "password": "ExamplePassword123!",
    "confirm_password": "ExamplePassword123!",
    "first_name": "Alex",
    "last_name": "Client",
    "ip": "203.0.113.10",
    "policy_agree": true
  }'
```

Optional profile fields are `address_1`, `address_2`, `city`, `company_name`, `country`, `region`, `zip_code`, `phone_number`, and `site_url`. The `201` response includes `subaccount_id`, `parent_id`, `email`, `active`, `ip`, and profile fields.

Set limits and status with the separate endpoints below. `limit` and `active` sent to the create endpoint are ignored.

## Read and update a profile

`GET /subaccounts/{Id}` returns the sub-account's identifiers, email, status, IP, and profile.

Use `PATCH /subaccounts/{Id}` to update it. Send `first_name`, `last_name`, `ip`, and `policy_agree: true`, plus any optional profile fields to change. To change the password, also send matching `password` and `confirm_password` fields.

```bash Terminal theme={"system"}
curl -X PATCH 'https://pro.api.serversmtp.com/api/v2/subaccounts/19302132' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "Alex",
    "last_name": "Client",
    "ip": "203.0.113.10",
    "policy_agree": true
  }'
```

The response is the updated sub-account profile.

## Set limits and status

| Method and path | JSON body | Response |
| - | - | - |
| `POST /subaccounts/{Id}/updatesubaccountsmtplimit` | `{"limit":2000}` | Updated active plan |
| `POST /subaccounts/{Id}/updatesubaccountstatus` | `{"active":true}` | Updated active plan |
| `GET /subaccounts/{Id}/active-plan` | None | Active plan |

`limit` must be an integer from `-1` to the parent account's limit. `-1` removes the sub-account-specific cap; the parent plan still applies. The period is given by `plan_limit_interval`.

The active-plan response includes `subaccount_id`, `parent_id`, `ip`, `active`, `limit`, `sent`, `last_used`, `plan_expiration`, `plan_limit_interval`, and `expired`. The `active` flag controls login availability; sending also requires an active subscription.

## Delete a sub-account

`DELETE /subaccounts/{Id}` soft-deletes the sub-account and frees its email address for reuse.

```bash Terminal theme={"system"}
curl -X DELETE 'https://pro.api.serversmtp.com/api/v2/subaccounts/19302132' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET'
```

## Access a sub-account session

`POST /subaccounts/authorize` accepts `{"email":"client@example.com"}` using the parent's management credentials. It returns an `auth` value for the sub-account session. Pass that value as the raw `Authorization` header on session-authenticated requests.

## Agency branding

| Method and path | Request or response |
| - | - |
| `GET /subaccounts/agency` | Returns `agency_name`, `agency_website`, `agency_footer`, and `logoUrl`. |
| `PATCH /subaccounts/agency` | JSON fields `agency_name` (maximum 128 characters), `agency_website` (128), and `agency_footer` (2048). Returns `{"message":"success"}`. |
| `POST /subaccounts/logo` | Multipart field `file` containing a PNG or JPEG. Returns `{"message":"success"}`. |
| `GET /subaccounts/logo` | Returns the logo image. |
| `DELETE /subaccounts/logo` | Removes the logo. Returns `{"message":"success"}`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.