Reseller API Tutorial

Reseller API

Manage sub-users under your reseller account: create clients, allocate credits from your balance, and track usage — every credit movement is logged for auditing.

Base URL: https://api.validemail.net Auth: reseller API key via token parameter Unlisted — shared by invitation

Unlisted documentation. This page was shared with you directly — please don't publish or link to it. Your sub-users should use the public API reference instead.

Endpoints at a glance

Method	Endpoint	Description
GET	`/v1/reseller/clients`	List your active sub-users.
GET	`/v1/reseller/usage`	Your balance plus allocation and usage per sub-user.
POST	`/v1/reseller/create`	Create a new sub-user and get their API key.
PUT	`/v1/reseller/edit`	Update a sub-user's name or email.
POST	`/v1/reseller/allocate`	Move credits from your balance to a sub-user.
DELETE	`/v1/reseller/delete/{apiKey}`	Delete a sub-user and refund their remaining credits to you.

All endpoints require your reseller API key as the token query parameter, e.g. /v1/reseller/usage?token=YOUR_RESELLER_KEY. Requests from accounts without the reseller role receive 401 Unauthorized.

Create a sub-user

POST https://api.validemail.net/v1/reseller/create?token={your_reseller_key}

Request body

{
  "email": "client@example.com",
  "name": "Client Name"
}

Response

{
  "apiKey": "NEW_SUB_USER_API_KEY"
}

Returns 409 Conflict when the email address is already registered. The new sub-user starts with zero credits — allocate some next.

Allocate credits

POST https://api.validemail.net/v1/reseller/allocate?token={your_reseller_key}

Request body

{
  "apiKey": "SUB_USER_API_KEY",
  "credits": 100
}

Moves credits from your reseller balance to the sub-user. The amount must be positive and cannot exceed your current balance — otherwise the API responds with 400 Bad Request. Responds 200 OK with an empty body on success.

Edit or delete a sub-user

PUT https://api.validemail.net/v1/reseller/edit?token={your_reseller_key}

Request body

{
  "apiKey": "SUB_USER_API_KEY",
  "email": "new@example.com",
  "name": "New Name"
}

Returns 404 Not Found for an unknown sub-user and 409 Conflict when the new email is already taken.

DELETE https://api.validemail.net/v1/reseller/delete/{subUserApiKey}?token={your_reseller_key}

Deactivates the sub-user and refunds their unused credits back to your reseller balance.

Track usage

GET https://api.validemail.net/v1/reseller/usage?token={your_reseller_key}

Response

{
  "resellerBalance": 5000,
  "users": [
    {
      "apiKey": "SUB_USER_API_KEY",
      "name": "Client Name",
      "email": "client@example.com",
      "allocated": 300,
      "used": 50,
      "balance": 250
    }
  ]
}

allocated is the lifetime total you have granted, used is how many verifications the sub-user has consumed, and balance is what they have left. GET /v1/reseller/clients returns the same users without the usage numbers.

Next steps

Your sub-users verify emails with the standard API using their own keys.

API Reference Bulk API