API Documentation

Current public Web API documentation aligned with production endpoints

Base URL:https://getgmailstore.com/api

Getting Started

Welcome to the current GmailStore public Web API. This page is only the live interface reference. It covers production endpoints only and does not provide API key application, usage statistics, or a developer console.

###

Base URL

All public endpoints use the main site domain:

text

https://getgmailstore.com/api

###

Make Your First Request

bash

curl -X GET https://getgmailstore.com/api/products

###

Response Format

The current API returns JSON and usually includes a success field:

json

{
  "success": true,
  "products": []
}

###

Important Note

This page is only the live API reference, not a developer console. When users place orders through the API, balance payments are deducted by order amount; API calls themselves are not billed separately. For automation or dedicated access, contact the administrator first.

Authentication

The current public product and order lookup endpoints do not require an API key. Completed orders can return account credentials with the order number and contact email.

Balance payments require the logged-in user Bearer token. Use the returned token in the request header:

text

Authorization: Bearer USER_TOKEN

text

POST /api/auth/login

Request body:

json

{
  "email": "[email protected]",
  "password": "your-password"
}

No Login Required

GET /api/products
GET /api/products/:idOrSlug
GET /api/orders/query?order_no=...&email=... (completed orders return account credentials; limited to 3 requests per IP per 60 seconds and 2 requests per order/email pair per 60 seconds)
GET /api/orders/:id/status?token=... (returns account details when the order access token is provided)

Login May Be Required

POST /api/orders/create requires a user Bearer token when the payment method is one of:

balance_cny
balance_crypto

Other payment methods, such as crypto, do not require login.

When users place orders through the API, balance payments are deducted by order amount; API calls themselves are not billed separately.

Admin and Internal APIs

/api/admin/*, /api/orders/clean, and similar endpoints are not public APIs. They require an admin token or an internal server secret.

API Endpoints

List Products

text

GET /api/products

Returns all active products with a single unit price.

Response Example:

json

{
  "success": true,
  "products": [
    {
      "id": "30a6d792-9e06-4023-85f4-736dfd9af07d",
      "slug": "gmail-usa-fresh",
      "name_zh": "谷歌企业/教育邮箱",
      "name_en": "Google Workspace / Education Email",
      "stock": 44,
      "min_quantity": 5,
      "price":
0.5
    }
  ]
}

Get Product Detail

text

GET /api/products/:idOrSlug

You can query by product id or slug.

Create Order

text

POST /api/orders/create

Parameter	Type	Required	Description
productId	string	Yes	Product ID. Use the `id` returned by `GET /api/products`, not the `slug`
quantity	integer	Yes	Purchase quantity. Maximum `200` per order and cannot exceed stock; minimum follows the product `min_quantity`
contactEmail	string	Yes	Email used for order contact and order lookup
paymentMethod	string	Yes	Payment method. Allowed values: `crypto`, `balance_cny`, `balance_crypto`, `alipay`, `wechat`
coin	string	No	Required only when `paymentMethod=crypto`. Allowed values: `trc20_usdt`, `erc20_usdt`, `bep20_usdt`, `btc`, `eth`, `trx`, `bnb`
couponCode	string	No	Coupon code. Omit it when unused

paymentMethod values:

Value	Description	Bearer Token Required
`crypto`	On-chain crypto payment. The response returns a payment address and expected amount	No
`balance_cny`	CNY balance payment. Deducts the order amount from `users.balance`	Yes
`balance_crypto`	USD/crypto balance payment. Deducts the converted amount from `users.balance_crypto`	Yes
`alipay`	External Alipay checkout. Availability follows `/api/payment-config`	No
`wechat`	External WeChat Pay checkout. Availability follows `/api/payment-config`	No

Balance payments require the logged-in user token in the request header:

text

Authorization: Bearer USER_TOKEN

Crypto Payment Example:

json

{
  "productId": "30a6d792-9e06-4023-85f4-736dfd9af07d",
  "quantity": 10,
  "contactEmail": "[email protected]",
  "paymentMethod": "crypto",
  "coin": "trc20_usdt"
}

CNY Balance Payment Example:

json

{
  "productId": "30a6d792-9e06-4023-85f4-736dfd9af07d",
  "quantity": 10,
  "contactEmail": "[email protected]",
  "paymentMethod": "balance_cny"
}

Query Order

text

GET /api/orders/query?order_no=GS2604291234ABCD&[email protected]

Both order number and email are required. When the order is completed, this endpoint returns the delivered account credentials. It is rate limited to 3 requests per IP per 60 seconds and 2 requests per order/email pair per 60 seconds.

Get Order Payment / Fulfillment Status

text

GET /api/orders/:id/status

Code Examples

Python

python

import requests

BASE_URL = "https://getgmailstore.com/api"

# List products
response = requests.get(f"{BASE_URL}/products")
products = response.json()["products"]

# Create order
order = requests.post(
    f"{BASE_URL}/orders/create",
    json={
        "productId": products[0]["id"],
        "quantity": 10,
        "contactEmail": "[email protected]",
        "paymentMethod": "crypto",
        "coin": "trc20_usdt"
    }
)
print(order.json())

Node.js

javascript

const BASE_URL = "https://getgmailstore.com/api";

// List products
const products = await fetch(`${BASE_URL}/products`);
const productList = await products.json();
console.log(productList);

// Create order
const order = await fetch(`${BASE_URL}/orders/create`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    productId: productList.products[0].id,
    quantity: 10,
    contactEmail: "[email protected]",
    paymentMethod: "crypto",
    coin: "trc20_usdt",
  }),
});
console.log(await order.json());

cURL

bash

# List products
curl -X GET https://getgmailstore.com/api/products

# Create order
curl -X POST https://getgmailstore.com/api/orders/create \
  -H "Content-Type: application/json" \
  -d '{"productId":"30a6d792-9e06-4023-85f4-736dfd9af07d","quantity":10,"contactEmail":"[email protected]","paymentMethod":"crypto","coin":"trc20_usdt"}'

# CNY balance payment
curl -X POST https://getgmailstore.com/api/orders/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer USER_TOKEN" \
  -d '{"productId":"30a6d792-9e06-4023-85f4-736dfd9af07d","quantity":10,"contactEmail":"[email protected]","paymentMethod":"balance_cny"}'

Error Code Reference

HTTP Status Codes

Code	Description
200	Success
400	Bad request parameters
401	Login or internal secret required
403	Insufficient permissions
404	Resource not found
500	Internal server error

Common Error Messages

Message	Description
Product not found	Product does not exist or is inactive
Insufficient stock	Not enough available stock
Insufficient balance	User balance is not enough
Minimum quantity is ...	Quantity is below the minimum order amount
Quantity cannot exceed 200	Quantity is above the maximum order amount
Please provide both order number and email	Order lookup requires both order number and email

Error Response Format

json

{
  "success": false,
  "error": "Product not found"
}

API Endpoints

List Products

text

GET /api/products

Returns all active products with a single unit price.

Response Example:

json

{
  "success": true,
  "products": [
    {
      "id": "30a6d792-9e06-4023-85f4-736dfd9af07d",
      "slug": "gmail-usa-fresh",
      "name_zh": "谷歌企业/教育邮箱",
      "name_en": "Google Workspace / Education Email",
      "stock": 44,
      "min_quantity": 5,
      "price":
0.5
    }
  ]
}

Get Product Detail

text

GET /api/products/:idOrSlug

You can query by product id or slug.

Create Order

text

POST /api/orders/create

Parameter	Type	Required	Description
productId	string	Yes	Product ID. Use the `id` returned by `GET /api/products`, not the `slug`
quantity	integer	Yes	Purchase quantity. Maximum `200` per order and cannot exceed stock; minimum follows the product `min_quantity`
contactEmail	string	Yes	Email used for order contact and order lookup
paymentMethod	string	Yes	Payment method. Allowed values: `crypto`, `balance_cny`, `balance_crypto`, `alipay`, `wechat`
coin	string	No	Required only when `paymentMethod=crypto`. Allowed values: `trc20_usdt`, `erc20_usdt`, `bep20_usdt`, `btc`, `eth`, `trx`, `bnb`
couponCode	string	No	Coupon code. Omit it when unused

paymentMethod values:

Value	Description	Bearer Token Required
`crypto`	On-chain crypto payment. The response returns a payment address and expected amount	No
`balance_cny`	CNY balance payment. Deducts the order amount from `users.balance`	Yes
`balance_crypto`	USD/crypto balance payment. Deducts the converted amount from `users.balance_crypto`	Yes
`alipay`	External Alipay checkout. Availability follows `/api/payment-config`	No
`wechat`	External WeChat Pay checkout. Availability follows `/api/payment-config`	No

Balance payments require the logged-in user token in the request header:

text

Authorization: Bearer USER_TOKEN

Crypto Payment Example:

json

{
  "productId": "30a6d792-9e06-4023-85f4-736dfd9af07d",
  "quantity": 10,
  "contactEmail": "[email protected]",
  "paymentMethod": "crypto",
  "coin": "trc20_usdt"
}

CNY Balance Payment Example:

json

{
  "productId": "30a6d792-9e06-4023-85f4-736dfd9af07d",
  "quantity": 10,
  "contactEmail": "[email protected]",
  "paymentMethod": "balance_cny"
}

Query Order

text

GET /api/orders/query?order_no=GS2604291234ABCD&[email protected]

Get Order Payment / Fulfillment Status

text

GET /api/orders/:id/status