Sub-Accounts API

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 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.

Dashboard setup

The Sub Accounts creation wizard has four steps:

Enter the email, a password set by the parent, and profile details.
Select a sending IP already assigned to the parent.
Review domain verification instructions.
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

Terminal

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.

Terminal

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:

{"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.

Terminal

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.

Terminal

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.

Terminal

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"}`.

Overview

Endpoints

Authentication

Dashboard setup

List sub-accounts

Check an email address

Create a sub-account

Read and update a profile

Set limits and status

Delete a sub-account

Access a sub-account session

Agency branding

​Authentication

​Dashboard setup

​List sub-accounts

​Check an email address

​Create a sub-account

​Read and update a profile

​Set limits and status

​Delete a sub-account

​Access a sub-account session

​Agency branding

Authentication

Dashboard setup

List sub-accounts

Check an email address

Create a sub-account

Read and update a profile

Set limits and status

Delete a sub-account

Access a sub-account session

Agency branding