User API Documentation

User management endpoints for creating, authenticating, and managing user accounts and user groups.

Create a User

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.create
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
RelUserGroupID	Integer	Yes	User group ID to assign the user to
EmailAddress	String	Yes	User's email address
Username	String	Yes	Username for login (must be unique)
Password	String	Yes	User's password (will be hashed)
TimeZone	String	Yes	User's timezone
Language	String	Yes	User's language code (e.g., 'en')
CompanyName	String	Conditional	Company name (required if FirstName not provided)
FirstName	String	Conditional	First name (required if CompanyName not provided)
LastName	String	No	Last name
Website	String	No	Website URL
OtherEmailAddresses	String	No	Additional email addresses
Street	String	No	Street address
City	String	No	City
State	String	No	State/Province
Zip	String	No	ZIP/Postal code
Country	String	No	Country
Phone	String	No	Phone number
PhoneVerified	Boolean	No	Phone verification status
Fax	String	No	Fax number
PreviewMyEmailAccount	String	No	Preview email account
PreviewMyEmailAPIKey	String	No	Preview email API key
ForwardToFriendHeader	String	No	Forward to friend header text
ForwardToFriendFooter	String	No	Forward to friend footer text
AccountStatus	String	No	Account status ('Enabled' or 'Disabled', default: 'Enabled')
AvailableCredits	Integer	No	Initial credits (default: 0)
ReputationLevel	String	No	Reputation level ('Trusted' or 'Untrusted', default: 'Trusted')
SignUpIPAddress	String	No	User signup IP address
SSOID	String	No	Single sign-on ID

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.create",
    "SessionID": "your-session-id",
    "RelUserGroupID": 1,
    "EmailAddress": "user@example.com",
    "Username": "newuser",
    "Password": "securepassword",
    "TimeZone": "America/New_York",
    "Language": "en",
    "FirstName": "John",
    "LastName": "Doe"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "UserID": 123
}

Error Response

{
  "Success": false,
  "ErrorCode": [1, 2, 3]
}

Error Codes

0: Success
1: Missing RelUserGroupID parameter
2: Missing EmailAddress parameter
3: Missing Username parameter
4: Missing Password parameter
6: Missing CompanyName or FirstName parameter
8: Missing TimeZone parameter
9: Missing Language parameter
10: Invalid email address format
11: Invalid user group ID
12: Username already exists
13: Email address already exists
14: Invalid language code
15: Invalid reputation level (must be 'Trusted' or 'Untrusted')
16: Maximum number of user accounts exceeded

User Login

POST /api.php

API Usage Notes

• No authentication required
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.login
SessionID	String	No	Session ID obtained from login
APIKey	String	Conditional	API key for authentication (alternative to username/password)
Username	String	Conditional	Username or email address (required if not using APIKey)
Password	String	Conditional	User's password (required if not using APIKey)
PasswordEncrypted	Boolean	No	Set to true if password is already MD5 hashed
TFACode	String	Conditional	Two-factor authentication code (required if 2FA is enabled)
TFARecoveryCode	String	No	Two-factor authentication recovery code
Disable2FA	Boolean	No	Set to true to disable 2FA verification

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.login",
    "Username": "john.doe",
    "Password": "securepassword"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "SessionID": "abc123def456",
  "UserInfo": {
    "UserID": 123,
    "Username": "john.doe",
    "EmailAddress": "john@example.com",
    "FirstName": "John",
    "LastName": "Doe",
    "AccountStatus": "Enabled"
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": [3],
  "ErrorText": ["Invalid login information"]
}

Error Codes

0: Success
1: Missing Username parameter
2: Missing Password parameter
3: Invalid login information
6: Invalid 2FA code or recovery code

Get Current User Information

POST /api.php

API Usage Notes

• Authentication required: User API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.current
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.current",
    "SessionID": "your-session-id"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "UserInfo": {
    "UserID": 123,
    "RelUserGroupID": 1,
    "EmailAddress": "user@example.com",
    "Username": "john.doe",
    "ReputationLevel": "Trusted",
    "UserSince": "2024-01-15 10:30:00",
    "FirstName": "John",
    "LastName": "Doe",
    "CompanyName": "",
    "Website": "",
    "Street": "",
    "Street2": "",
    "City": "",
    "State": "",
    "Zip": "",
    "Country": "",
    "VAT": "",
    "Phone": "",
    "PhoneVerified": 0,
    "Fax": "",
    "TimeZone": "America/New_York",
    "LastActivityDateTime": "2024-12-28 10:00:00",
    "AccountStatus": "Enabled",
    "AvailableCredits": 1000,
    "2FA_Enabled": "No",
    "2FA_RecoveryKey": "",
    "SSOID": "",
    "GroupInfo": {
      "UserGroupID": 1,
      "GroupName": "Standard Users",
      "GroupPlanName": "Standard Plan",
      "DefaultSenderDomain": "example.com"
    },
    "MFA_QRCode": "otpauth://totp/...",
    "MFA_SecretKey": "ABCDEF123456",
    "SubscriptionID": false
  },
  "Usage": {
    "EmailGateway_TotalSentThisMonth": 500,
    "EmailGateway_TotalSentAllTime": 5000,
    "Limit_Monthly": 10000,
    "Limit_Lifetime": 100000
  },
  "SendRateLimits": {
    "EmailGateway": {
      "RateLimits": {},
      "SendRates": {}
    },
    "DefaultSenderDomain": {
      "MonthlyLimit": 5000,
      "SendRates": 500,
      "RemainingMonthlyQuota": 4500
    }
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Authentication required

Get User Information

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.get
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserID	Integer	Conditional	User ID (required if EmailAddress not provided)
EmailAddress	String	Conditional	Email address (required if UserID not provided)

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.get",
    "SessionID": "your-session-id",
    "UserID": 123
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "UserInformation": {
    "UserID": 123,
    "RelUserGroupID": 1,
    "EmailAddress": "user@example.com",
    "Username": "john.doe",
    "FirstName": "John",
    "LastName": "Doe",
    "GroupInformation": {}
  },
  "LimitUtilization": {
    "Subscribers": {"Used": 100, "Limit": 1000},
    "Lists": {"Used": 5, "Limit": 10}
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Missing UserID or EmailAddress parameter
3: User not found

Update User

POST /api.php

API Usage Notes

• Authentication required: Admin API Key or User API Key
• Required permissions: User.Update
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.update
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserID	Integer	Yes	User ID to update
EmailAddress	String	No	New email address
Username	String	No	New username
Password	String	No	New password (will be hashed)
FirstName	String	No	First name
LastName	String	No	Last name
CompanyName	String	No	Company name
Website	String	No	Website URL
OtherEmailAddresses	String	No	Additional email addresses
Street	String	No	Street address
Street2	String	No	Street address line 2
City	String	No	City
State	String	No	State/Province
Zip	String	No	ZIP/Postal code
Country	String	No	Country
VAT	String	No	VAT number
Phone	String	No	Phone number
PhoneVerified	Boolean	No	Phone verification status
Fax	String	No	Fax number
TimeZone	String	No	Timezone
Language	String	No	Language code
AccountStatus	String	No	Account status (admin only)
AvailableCredits	Integer	No	Available credits (admin only)
RelUserGroupID	Integer	No	User group ID (admin only)
ReputationLevel	String	No	Reputation level (admin only)
RateLimits	String	No	JSON string of rate limits
CustomEmailHeaders	String	No	Custom email headers
WhiteListedEmailAddresses	String	No	Whitelisted email addresses
Enable2FA	String	No	Set to 'true' to enable 2FA
2FACode	String	Conditional	2FA code (required when enabling 2FA)
Cancel2FA	String	No	Set to 'true' to disable 2FA

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.update",
    "SessionID": "your-session-id",
    "UserID": 123,
    "FirstName": "Jane",
    "LastName": "Smith"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}

Error Response

{
  "Success": false,
  "ErrorCode": 2
}

Error Codes

0: Success
1: Missing UserID parameter
2: User can only update their own account
3: PreviewMyEmail connection error
4: Invalid 2FA code
5: User not found
6: Email address or username already exists

Get Monthly User Snapshot

POST /api.php

API Usage Notes

• Authentication required: Admin API Key or User API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.snapshot
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserID	Integer	Conditional	User ID (required if not logged in and EmailAddress not provided)
EmailAddress	String	Conditional	Email address (alternative to UserID)
Month	String	Yes	Month in YYYY-MM format (e.g., '2024-12')

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.snapshot",
    "SessionID": "your-session-id",
    "Month": "2024-12"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "CampaignsSent": 15,
  "EmailsSent": 5000,
  "Subscribers": 1500,
  "Lists": 8
}

Error Response

{
  "Success": false,
  "ErrorCode": [3]
}

Error Codes

0: Success
1: Missing EmailAddress parameter
2: Missing UserID parameter
3: Missing Month parameter
4: Invalid month format
5: User not found

Get User Statistics

POST /api/v1/user.stats

API Usage Notes

• Authentication required: User API Key
• Rate limit: 100 requests per 60 seconds
• Legacy endpoint access via /api.php is also supported

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.stats
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
StartDate	String	Yes	Start date in YYYY-MM-DD format
EndDate	String	Yes	End date in YYYY-MM-DD format
Aggregation	String	Yes	Aggregation type: 'daily', 'weekly', or 'monthly'

Example Request

curl -X POST https://example.com/api/v1/user.stats \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.stats",
    "SessionID": "your-session-id",
    "StartDate": "2024-01-01",
    "EndDate": "2024-12-31",
    "Aggregation": "monthly"
  }'

Success Response

{
  "NumberOfLists": 12,
  "TotalActiveLists": 9,
  "TotalActiveSubscribers": 15234,
  "TotalSegments": 28,
  "AvgOpenRate30dWeighted": 0.2418,
  "AvgClickRate30dWeighted": 0.0327,
  "AvgCTOR30dWeighted": 0.1352,
  "AvgForwardRate30dWeighted": 0.0014,
  "AvgBrowserViewRate30dWeighted": 0.0119,
  "New Subscribers": {
    "2024-01-01": 12,
    "2024-01-02": 18
  },
  "Sent Emails": {
    "2024-01-01": 250,
    "2024-01-02": 300
  },
  "Opens": {
    "2024-01-01": 80,
    "2024-01-02": 95
  }
}

Error Response

{
  "Errors": [
    {"Code": 1, "Message": "Missing StartDate parameter"}
  ]
}

Error Codes

1: Missing StartDate parameter
2: Missing EndDate parameter
3: Missing Aggregation parameter
4: Invalid Aggregation value (must be 'daily', 'weekly', or 'monthly')
6: Statistics retrieval error

Top-level overall fields

The response is the merge of two payloads: a stat-strip header (the overall fields below) plus the time-series breakdown for each metric (keyed by metric title — New Subscribers, Sent Emails, Opens, etc).

Field	Type	Description
NumberOfLists	Integer	Total lists owned by the user, including archived. Back-compat with pre-v5.9.x consumers.
TotalActiveLists	Integer	Lists with ArchivedAt IS NULL.
TotalActiveSubscribers	Integer	Sum of ActiveSubscriberCount (denormalized) across non-archived lists. Defines "active" as Subscribed AND BounceType != 'Hard', matching the count lists.get displays.
TotalSegments	Integer	Sum of SegmentCount (denormalized) across non-archived lists.
AvgOpenRate30dWeighted	Float | null	Subscriber-weighted average 30-day open rate across non-archived lists, computed as Σ(ActiveSubscriberCount × UniqueOpens) / Σ(ActiveSubscriberCount × TotalSent). null when no list in the user's active set had any sends in the 30-day window.
AvgClickRate30dWeighted	Float | null	Subscriber-weighted average 30-day click rate. Same shape and weighting basis as AvgOpenRate30dWeighted but with UniqueClicks in the numerator. null when no sends. (Added in v5.9.1, issue #1960.)
AvgCTOR30dWeighted	Float | null	Subscriber-weighted average 30-day Click-To-Open Rate, computed as Σ(ActiveSubscriberCount × UniqueClicks) / Σ(ActiveSubscriberCount × UniqueOpens). Different denominator basis from the other rates: lists with zero opens are skipped (not zero-weighted) so they don't drag the average to zero. null when no opens. (Added in v5.9.1, issue #1960.)
AvgForwardRate30dWeighted	Float | null	Subscriber-weighted average 30-day forward rate. Same shape as AvgOpenRate30dWeighted with UniqueForwards in the numerator. (Added in v5.9.1, issue #1960.)
AvgBrowserViewRate30dWeighted	Float | null	Subscriber-weighted average 30-day "view in browser" rate. Same shape as AvgOpenRate30dWeighted with UniqueBrowserViews in the numerator. (Added in v5.9.1, issue #1960.)

Migration note (v5.9.x): TotalActiveSubscribers previously summed across all lists (including archived) using a slightly stricter criterion (BounceType = 'Not Bounced', excluding soft bounces). Both changes were intentional: the new value (a) excludes archived lists — matching the lists.get browse display — and (b) uses BounceType != 'Hard' to align with Subscribers::GetActiveTotal. For a user with no archived lists and a clean deliverability footprint the difference is negligible. For users with many archived lists or noticeable soft-bounce volume the value will shift; treat the new figure as the canonical "subscribers I currently market to."

Switch to User Account

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.switch
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserID	Integer	Yes	User ID to switch to
PrivilegeType	String	No	Privilege type: 'Default' or 'Full' (default: 'Default')

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.switch",
    "SessionID": "your-admin-session-id",
    "UserID": 123,
    "PrivilegeType": "Full"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "SessionID": "new-session-id",
  "UserInfo": {
    "UserID": 123,
    "Username": "john.doe"
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Missing UserID parameter
2: User not found
3: Invalid privilege type (must be 'Default' or 'Full')

Send Password Reminder

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.passwordremind
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
EmailAddress	String	Yes	User's email address
CustomResetLink	String	No	Base64 encoded custom reset link template
ReturnParams	Boolean	No	Set to true to return reset token and link
AdminAPIKey	String	No	Admin API key for custom email settings
ResetEmailSubject	String	No	Custom email subject (requires AdminAPIKey)
ResetEmailContent	String	No	Custom email content (requires AdminAPIKey)

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.passwordremind",
    "SessionID": "your-session-id",
    "EmailAddress": "user@example.com"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "PasswordResetToken": "",
  "PasswordResetLink": ""
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Missing EmailAddress parameter
2: Invalid email address format
3: Email address not found (Note: For security, this returns success even if not found)

Reset User Password

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.passwordreset
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserID	String	Yes	Password reset token (from passwordremind)
AdminAPIKey	String	No	Admin API key for custom password
NewPassword	String	No	Custom new password (requires AdminAPIKey)
DontSendNewPasswordEmail	String	No	Set to 'true' to skip email (requires AdminAPIKey)
ShowPassword	Boolean	No	Set to true to include password in email

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.passwordreset",
    "UserID": "reset-token-here"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "WoocommerceUserId": false
}

Error Response

{
  "Success": false,
  "ErrorCode": [2]
}

Error Codes

0: Success
1: Missing UserID parameter
2: Invalid reset token or user not found

Create API Key

POST /api/v1/user.apikey

API Usage Notes

• Authentication required: User API Key
• Required permissions: User.Update
• Rate limit: 100 requests per 60 seconds
• Legacy endpoint access via /api.php is also supported

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.apikey.create
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
Note	String	Yes	Administrative note for the API key
BoundIPAddress	String	No	IP address to bind the key to

Example Request

curl -X POST https://example.com/api/v1/user.apikey \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.apikey.create",
    "SessionID": "your-session-id",
    "Note": "Production API key"
  }'

Success Response

{
  "Success": true,
  "APIKeyID": "5",
  "APIKey": {
    "APIKey": "1234-5678-9abc-def0",
    "Note": "Production API key",
    "IPAddress": "",
    "BoundIPAddress": "",
    "CreatedAt": "2026-05-22 20:45:48",
    "LastUsedAt": null,
    "LastUsedIP": null,
    "RequestCount": 0
  }
}

Error Response

{
  "Errors": [
    {"Code": 1, "Message": "Missing administrative note parameter"}
  ]
}

Error Codes

1: Missing administrative note parameter
3: API key create process failed
4: New API key create process has failed

Response Fields (APIKey object):

Field	Type	Description
APIKey	String	The generated API key token.
Note	String	Administrative note supplied at creation.
IPAddress	String	Deprecated — kept for backward compatibility. Same value as BoundIPAddress. Prefer BoundIPAddress in new integrations.
BoundIPAddress	String	IP address the key is bound to, or "" if unbound.
CreatedAt	String (DATETIME)	Creation timestamp (UTC, YYYY-MM-DD HH:MM:SS).
LastUsedAt	String | null	Last time this key was used to authenticate (always null for a freshly created key).
LastUsedIP	String | null	Client IP recorded at last use, null if never used.
RequestCount	Integer	Lifetime number of authentications with this key (always 0 for a freshly created key).

Counter semantics

RequestCount and LastUsedAt are bumped each time the key is used to start a session via User.Login (with the APIKey parameter). They do not count every individual REST request made within a session — once a client has a SessionID, subsequent calls authenticate with session credentials and do not re-touch the API key. Treat RequestCount as "how many times has this integration checked in?", which is what an operator cares about when answering "is this key still in use anywhere?".

:::

Delete API Key

POST /api/v1/user.apikey.delete

API Usage Notes

• Authentication required: User API Key
• Required permissions: User.Update
• Rate limit: 100 requests per 60 seconds
• Legacy endpoint access via /api.php is also supported

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.apikey.delete
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
APIKeyID	Integer	Yes	API key ID to delete

Example Request

curl -X POST https://example.com/api/v1/user.apikey.delete \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.apikey.delete",
    "SessionID": "your-session-id",
    "APIKeyID": 5
  }'

Success Response

{
  "Success": true
}

Error Response

{
  "Errors": [
    {"Code": 1, "Message": "Missing APIKeyID parameter"}
  ]
}

Error Codes

1: Missing APIKeyID parameter
2: API key not found

List API Keys

GET /api/v1/user.apikeys

API Usage Notes

• Authentication required: User API Key
• Required permissions: User.Update
• Rate limit: 100 requests per 60 seconds
• Legacy endpoint access via /api.php is also supported

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: user.apikey.list
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication

Example Request

curl -X GET https://example.com/api/v1/user.apikeys \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "user.apikey.list",
    "SessionID": "your-session-id"
  }'

Success Response

{
  "Success": true,
  "APIKeys": [
    {
      "APIKeyID": 17,
      "APIKey": "7c7c-0a2b-66e2-3738-d373-5362-7ab9-9a68",
      "Note": "Shopify sync",
      "BoundIPAddress": "",
      "CreatedAt": "2026-02-04 09:12:33",
      "LastUsedAt": "2026-04-25 14:07:11",
      "LastUsedIP": "52.14.72.10",
      "RequestCount": 12840
    }
  ]
}

Error Response

{
  "Errors": []
}

Error Codes

No specific error codes for this endpoint

Response Fields (each entry in APIKeys[]):

Field	Type	Description
APIKeyID	Integer	Internal numeric ID of the key.
APIKey	String	The API key token.
Note	String	Administrative note supplied at creation.
BoundIPAddress	String	IP address the key is bound to, or "" if unbound.
CreatedAt	String (DATETIME)	Creation timestamp. Keys that pre-date the usage-tracking migration return the sentinel "1970-01-01 00:00:00" — clients should render this as "Unknown".
LastUsedAt	String | null	Last time this key was used to authenticate, or null if the key has never been used.
LastUsedIP	String | null	Client IP recorded at last use (IPv4 or IPv6), null if never used.
RequestCount	Integer	Lifetime number of authentications with this key. See counter semantics on the Create endpoint above.

Get Users List

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: users.get
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
RecordsPerRequest	Integer	No	Number of records per page (default: 25)
RecordsFrom	Integer	No	Starting record offset (default: 0)
OrderField	String	No	Field to order by
OrderType	String	No	Order direction: 'ASC' or 'DESC'
RelUserGroupID	Mixed	No	User group ID, array of IDs, or special value ('Online', 'Enabled', 'Disabled', 'Trusted', 'Untrusted')
RelUserCategoryID	Integer	No	User category ID (-1 for uncategorized)
SearchField	String	No	Field to search in
SearchKeyword	String	No	Search keyword
ReturnStats	Boolean	No	Set to true to include statistics
IncludeLimitUtilization	Boolean	No	Set to true to include limit utilization data

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "users.get",
    "SessionID": "your-session-id",
    "RecordsPerRequest": 25,
    "RecordsFrom": 0,
    "OrderField": "UserID",
    "OrderType": "DESC"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "Users": [
    {
      "UserID": 123,
      "Username": "john.doe",
      "EmailAddress": "john@example.com",
      "GroupInformation": {}
    }
  ],
  "TotalUsers": 150
}

Error Response

{
  "Success": false,
  "ErrorCode": 0
}

Error Codes

0: Success

Delete Users

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)
• Note: Not available in demo mode

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: users.delete
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
Users	String	Yes	Comma-separated list of user IDs to delete

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "users.delete",
    "SessionID": "your-session-id",
    "Users": "123,124,125"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Missing Users parameter

Get Users Status

GET /api/v1/users.status

API Usage Notes

• Authentication required: Admin API Key
• Rate limit: 100 requests per 60 seconds
• Legacy endpoint access via /api.php is also supported

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: users.status
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
Duration	Integer	No	Number of days to look back (1-90, default: 30)

Example Request

curl -X GET https://example.com/api/v1/users.status \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "users.status",
    "SessionID": "your-session-id",
    "Duration": 30
  }'

Success Response

{
  "Success": true,
  "Users": [
    {
      "UserID": 123,
      "Status": "active",
      "LastActivity": "2024-12-28 10:00:00"
    }
  ],
  "Summary": {
    "ActiveUsers": 50,
    "IdleUsers": 10
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "Failed to retrieve users status"
}

Error Codes

0: Success
1: Failed to retrieve users status

Create User Group

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: usergroup.create
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
GroupName	String	Yes	Name of the user group
SubscriberAreaLogoutURL	String	Yes	Subscriber area logout URL
LimitSubscribers	Integer	Yes	Maximum number of subscribers
LimitLists	Integer	Yes	Maximum number of lists
LimitCampaignSendPerPeriod	Integer	Yes	Campaign send limit per period
LimitEmailSendPerPeriod	Integer	Yes	Email send limit per period
LimitEmailSendPerDay	Integer	Yes	Email send limit per day
RelThemeID	Integer	Yes	Theme ID
ForceUnsubscriptionLink	String	Yes	'Enabled' or 'Disabled'
ForceRejectOptLink	String	Yes	'Enabled' or 'Disabled'
DefaultRateLimits	String	No	JSON-encoded rate limits with SMS and EmailGateway buckets, each containing Minute/Hour/Day/Week/Month/Year integer counts (-1 = unlimited). Posted values are deep-merged over the canonical defaults, so a partial payload (only one bucket, or only some intervals) preserves the missing keys at -1. Omit to store the full all--1 defaults.
CustomEmailHeaders	String	No	JSON-encoded SMTP header overrides for users in this group (e.g. {"Add":{"X-Header":"value"},"Remove":["X-Other"]}).
Options	Object	No	JSON object of per-group options (e.g. TargetDeliveryServerID_Marketing, EmailGatewayDNSTemplate, DefaultSenderDomain, EnableSenderInfo). Pass as an object — the endpoint JSON-encodes it.
SubscriptionPlan	String	No	Subscription plan identifier for the group.

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "usergroup.create",
    "SessionID": "your-session-id",
    "GroupName": "Premium Users",
    "SubscriberAreaLogoutURL": "https://example.com/logout",
    "LimitSubscribers": 10000,
    "LimitLists": 50,
    "LimitCampaignSendPerPeriod": 100,
    "LimitEmailSendPerPeriod": 50000,
    "LimitEmailSendPerDay": 5000,
    "RelThemeID": 1,
    "ForceUnsubscriptionLink": "Enabled",
    "ForceRejectOptLink": "Enabled"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "UserGroupID": 5
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Missing GroupName parameter
2: Missing SubscriberAreaLogoutURL parameter
5: Missing LimitSubscribers parameter
6: Missing LimitLists parameter
7: Missing LimitCampaignSendPerPeriod parameter
8: Missing RelThemeID parameter
17: Missing ForceUnsubscriptionLink parameter
18: Missing ForceRejectOptLink parameter
19: Invalid theme ID
20: Missing LimitEmailSendPerPeriod parameter
22: Invalid send method
23: Invalid SMTP secure setting
24: Invalid SMTP auth setting
25: Email settings test failed

Update User Group

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: usergroup.update
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserGroupID	Integer	Yes	User group ID to update
GroupName	String	Yes	Name of the user group
SubscriberAreaLogoutURL	String	Yes	Subscriber area logout URL
LimitSubscribers	Integer	Yes	Maximum number of subscribers
LimitLists	Integer	Yes	Maximum number of lists
LimitCampaignSendPerPeriod	Integer	Yes	Campaign send limit per period
LimitEmailSendPerPeriod	Integer	Yes	Email send limit per period
LimitEmailSendPerDay	Integer	Yes	Email send limit per day
RelThemeID	Integer	Yes	Theme ID
ForceUnsubscriptionLink	String	Yes	'Enabled' or 'Disabled'
ForceRejectOptLink	String	Yes	'Enabled' or 'Disabled'
DefaultRateLimits	String	No	JSON-encoded rate limits with SMS and EmailGateway buckets, each containing Minute/Hour/Day/Week/Month/Year integer counts (-1 = unlimited). Posted values are deep-merged over the canonical defaults, so a partial payload (only one bucket, or only some intervals) preserves the missing keys at -1. Omit the field entirely to keep the existing row's value.
CustomEmailHeaders	String	No	JSON-encoded SMTP header overrides for users in this group (e.g. {"Add":{"X-Header":"value"},"Remove":["X-Other"]}). Omit to keep the existing row's value.
Options	Object	No	JSON object of per-group options (e.g. TargetDeliveryServerID_Marketing, EmailGatewayDNSTemplate, DefaultSenderDomain, EnableSenderInfo). Pass as an object — the endpoint JSON-encodes it. Omit to keep the existing row's value.
SubscriptionPlan	String	No	Subscription plan identifier for the group. Omit to keep the existing row's value.

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "usergroup.update",
    "SessionID": "your-session-id",
    "UserGroupID": 5,
    "GroupName": "Premium Plus Users",
    "SubscriberAreaLogoutURL": "https://example.com/logout",
    "LimitSubscribers": 20000,
    "LimitLists": 100,
    "LimitCampaignSendPerPeriod": 200,
    "LimitEmailSendPerPeriod": 100000,
    "LimitEmailSendPerDay": 10000,
    "RelThemeID": 1,
    "ForceUnsubscriptionLink": "Enabled",
    "ForceRejectOptLink": "Enabled",
    "DefaultRateLimits": "{\"SMS\":{\"Minute\":-1,\"Hour\":-1,\"Day\":-1,\"Week\":-1,\"Month\":-1,\"Year\":-1},\"EmailGateway\":{\"Minute\":100,\"Hour\":5000,\"Day\":-1,\"Week\":-1,\"Month\":-1,\"Year\":-1}}"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0
}

Error Response

{
  "Success": false,
  "ErrorCode": [20]
}

Error Codes

0: Success
1: Missing GroupName parameter
2: Missing SubscriberAreaLogoutURL parameter
5: Missing LimitSubscribers parameter
6: Missing LimitLists parameter
7: Missing LimitCampaignSendPerPeriod parameter
8: Missing RelThemeID parameter
17: Missing ForceUnsubscriptionLink parameter
18: Missing ForceRejectOptLink parameter
19: Invalid theme ID
20: Missing UserGroupID parameter
21: User group not found
22: Invalid send method
23: Invalid SMTP secure setting
24: Invalid SMTP auth setting
25: Email settings test failed

Get User Group

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: usergroup.get
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserGroupID	Integer	Yes	User group ID to retrieve

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "usergroup.get",
    "SessionID": "your-session-id",
    "UserGroupID": 5
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "UserGroup": {
    "UserGroupID": 5,
    "GroupName": "Premium Users",
    "LimitSubscribers": 10000,
    "LimitLists": 50
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Missing UserGroupID parameter
2: User group not found

Delete User Group

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)
• Note: Not available in demo mode

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: usergroup.delete
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserGroupID	String	Yes	Comma-separated list of user group IDs to delete

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "usergroup.delete",
    "SessionID": "your-session-id",
    "UserGroupID": "5,6,7"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Missing UserGroupID parameter
4: Cannot delete the last user group

Duplicate User Group

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: usergroup.duplicate
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
UserGroupID	Integer	Yes	User group ID to duplicate

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "usergroup.duplicate",
    "SessionID": "your-session-id",
    "UserGroupID": 5
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "UserGroupID": 8
}

Error Response

{
  "Success": false,
  "ErrorCode": [2]
}

Error Codes

0: Success
1: Missing UserGroupID parameter
2: User group not found

Get All User Groups

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: usergroups.get
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "usergroups.get",
    "SessionID": "your-session-id"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "UserGroups": [
    {
      "UserGroupID": 1,
      "GroupName": "Standard Users",
      "LimitSubscribers": 1000,
      "DeliveryServerAssignments": {
        "Marketing": {
          "DeliveryServerID": 5,
          "DeliveryServerName": "Primary SMTP Server"
        },
        "Transactional": {
          "DeliveryServerID": 5,
          "DeliveryServerName": "Primary SMTP Server"
        },
        "AutoResponder": {
          "DeliveryServerID": 0,
          "DeliveryServerName": ""
        }
      }
    },
    {
      "UserGroupID": 2,
      "GroupName": "Premium Users",
      "LimitSubscribers": 10000,
      "DeliveryServerAssignments": {
        "Marketing": {
          "DeliveryServerID": 8,
          "DeliveryServerName": "High Volume SMTP"
        },
        "Transactional": {
          "DeliveryServerID": 8,
          "DeliveryServerName": "High Volume SMTP"
        },
        "AutoResponder": {
          "DeliveryServerID": 8,
          "DeliveryServerName": "High Volume SMTP"
        }
      }
    }
  ]
}

Error Response

{
  "Success": false,
  "ErrorCode": 0
}

Error Codes

0: Success

Response Field Reference:

Field	Type	Description
UserGroups	Array	List of all user groups
UserGroupID	Integer	Unique identifier for the user group
GroupName	String	Display name of the user group
DeliveryServerAssignments	Object	Delivery server assignments per channel type. Contains three keys: Marketing, Transactional, and AutoResponder. Each contains DeliveryServerID (0 if not assigned) and DeliveryServerName (empty string if not assigned)

Add Credits (DEPRECATED)

DEPRECATED

This endpoint is deprecated and will be removed in a future version. There is no replacement endpoint.

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)
• Status: DEPRECATED - No replacement available

Order Payment (DEPRECATED)

DEPRECATED

This endpoint is deprecated and will be removed in a future version. There is no replacement endpoint.

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)
• Status: DEPRECATED - No replacement available

Get Payment Periods (DEPRECATED)

DEPRECATED

This endpoint is deprecated and will be removed in a future version. There is no replacement endpoint.

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)
• Status: DEPRECATED - No replacement available

Update Payment Periods (DEPRECATED)

DEPRECATED

This endpoint is deprecated and will be removed in a future version. There is no replacement endpoint.

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)
• Status: DEPRECATED - No replacement available

Change Subscription Payment (DEPRECATED)

DEPRECATED

This endpoint is deprecated and will be removed in a future version. There is no replacement endpoint.

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)
• Status: DEPRECATED - No replacement available

Upgrade Subscription (DEPRECATED)

DEPRECATED

This endpoint is deprecated and will be removed in a future version. There is no replacement endpoint.

POST /api.php

API Usage Notes

• Authentication required: Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)
• Status: DEPRECATED - No replacement available