API Reference

The S-PRO v12.3 API is built on Google Apps Script Web App architecture. All requests must be routed to your unique deployment endpoint.

Endpoint Base https://script.google.com/macros/s/DEPLOYMENT_ID/exec
Architectural Specs

Protocol Details

CORS Support

Automatic Cross-Origin Resource Sharing (CORS) handling via ContentService. Supports cross-domain fetch requests from web browsers.

V8 Runtime

Optimized JavaScript V8 engine compliance for high-speed variable processing and modern ES6+ syntax.

Atomic Locks

Script-level mutex using LockService to ensure thread-safe spreadsheet writes during concurrent API hits.

Mime-Type Strategy

Standardized JSON outputs for administrative actions and TEXT for public webhooks.

Full CRUD Capabilities

The .gs master engine implements a complete CRUD lifecycle for subscriber nodes:

Create

New node injection via SYNC method or public subscribe action.

Read

Data retrieval for the dashboard UI and Gmail History retrieval via History Engine.

Update

Metric increments (Opens/Clicks) and status changes via the updateMetric utility.

Delete

Physical node removal via the public unsubscribe webhook or Admin console actions.

Secure

Authentication Protocol

The API handles security based on request type:

  • Public Actions (GET): Parameter-based email identifiers (no key required) - subscribe, unsubscribe, track, click.
  • Admin Actions (POST): Requires the Master Key (apple123) in the JSON payload + valid session token.
  • Session Actions (GET): Requires a valid token generated via the login endpoint with 24-hour expiration.
  • Rate Limiting: 5 failed login attempts triggers 15-minute account lockout.
GET

/track

?action=track&email={address}

Triggers the Pixel Engine to increment the "Opens" column for the specified subscriber ID.

Case Usage: Email Pixel

<!-- Embed in HTML Email body -->
<img src="SCRIPT_URL?action=track&email=user@domain.com" width="1" height="1" />
GET

/click

?action=click&email={address}&redirect={url}

Tracks CTA clicks and increments the "Clicks" column. Supports automatic redirect to target URL after tracking.

Case Usage: CTA Button Link

<!-- Trackable CTA link in email -->
<a href="SCRIPT_URL?action=click&email=user@domain.com&redirect=https://example.com">
  Click Here
</a>
GET

/unsubscribe

?action=unsubscribe&email={address}

Removes subscriber from the database. This action permanently deletes the subscriber row from the "Subscribers" sheet.

Case Usage: Unsubscribe Link

<!-- Unsubscribe link in email footer -->
<a href="SCRIPT_URL?action=unsubscribe&email=user@domain.com">
  Unsubscribe
</a>
GET

/subscribe

?action=subscribe&email={address}&name={name}

Automated node registration. This action validates if the node exists, appends to the "Subscribers" sheet, and dispatches the Welcome Email if SEND_WELCOME_EMAIL is enabled.

Case Usage: HTML Form Webhook

// Direct link usage
<a href="SCRIPT_URL?action=subscribe&email=lead@site.com&name=John Doe">One-Click Subscribe</a>
GET

/login

?action=login&password={password}

Creates admin session with UUID token. Includes rate limiting (5 attempts max, 15-minute lockout) and 24-hour token expiration.

Response Object

{
  "success": true,
  "message": "Login successful",
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": 1705864800000
}
GET

/logout

?action=logout&token={session_token}

Terminates admin session by removing token from cache storage.

Response Object

{
  "success": true,
  "message": "Logged out successfully"
}
GET

/viewAll

?action=viewAll&key=apple123

Returns complete subscriber list with statistics. Requires master key for authentication. No session token required.

Response Object

{
  "data": [...],
  "stats": {
    "total": 150,
    "active": 142,
    "totalOpens": 450,
    "totalClicks": 89,
    "remainingEmails": 450,
    "systemStatus": "ONLINE"
  }
}
POST

sendEmail

Dispatches professional HTML emails through the Gmail Hub. Requires both master key and valid session token.

Request Payload (JSON)

{
  "key": "apple123",
  "token": "SESSION_TOKEN_UUID",
  "action": "sendEmail",
  "to": "recipient@example.com",
  "subject": "Order Confirmation",
  "body": "<h1>Hello World</h1>",
  "senderName": "S-PRO Support"
}
POST

addSubscriber

Adds new subscriber to database. Requires both master key and valid session token. Prevents duplicate emails.

Request Payload (JSON)

{
  "key": "apple123",
  "token": "SESSION_TOKEN_UUID",
  "action": "addSubscriber",
  "email": "user_452@gmail.com",
  "name": "John Doe"
}
POST

updateStatus

Updates subscriber status (active/unsubscribed). Requires both master key and valid session token.

Request Payload (JSON)

{
  "key": "apple123",
  "token": "SESSION_TOKEN_UUID",
  "action": "updateStatus",
  "email": "user@example.com",
  "status": "unsubscribed"
}
POST

SYNC_NODE (Legacy)

Legacy manual subscriber injection. This method is protected by the LockService concurrency lock (20s) to ensure data integrity during mass imports.

Node Injection Schema

{
  "key": "apple123",
  "token": "SESSION_TOKEN_UUID",
  "email": "user_452@gmail.com",
  "name": "John Doe"
}
GET

getQuota

Monitors the MailApp.getRemainingDailyQuota() sensor. Critical for scaling outbound campaigns.

Response Object

{ "remaining": 1495 }
GET

getConversation

Searches the Gmail Hub History for threads associated with a specific email node. Limited to the most recent 15 messages.

Query Parameters

  • ?action=getConversation
  • &token=SESSION_TOKEN_UUID
  • &email=target@mail.com