Skip to content

Users API Documentation

Retrieve Current User Information

POST /api.php

This endpoint retrieves the current user's public information, including personal details, group information, multi-factor authentication (MFA) setup, WooCommerce subscription ID, and email gateway usage and rate limits.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandUser.CurrentYes
bash
curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"SessionID": "your-session-id", "APIKey": "your-api-key", "Command": "User.Current"}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "UserInfo": {
    "UserID": "12345",
    "RelUserGroupID": "1",
    "EmailAddress": "user@example.com",
    "Username": "johndoe",
    "ReputationLevel": "5",
    "UserSince": "2020-01-01T00:00:00Z",
    "FirstName": "John",
    "LastName": "Doe",
    "CompanyName": "Example Corp",
    "Website": "https://www.example.com",
    "Street": "123 Example St",
    "Street2": "Suite 100",
    "City": "Example City",
    "State": "EX",
    "Zip": "12345",
    "Country": "Exampleland",
    "VAT": "EX1234567",
    "Phone": "+1234567890",
    "PhoneVerified": "Yes",
    "Fax": "+1234567891",
    "TimeZone": "UTC",
    "LastActivityDateTime": "2023-01-01T12:00:00Z",
    "AccountStatus": "Active",
    "AvailableCredits": "100",
    "2FA_Enabled": "No",
    "2FA_RecoveryKey": "abcd-efgh-ijkl-mnop",
    "SSOID": "sso-12345",
    "GroupInfo": {
      "UserGroupID": "1",
      "GroupName": "Standard",
      "GroupPlanName": "Basic Plan"
      // Other user group details
      "Options": {
        // Other user group options
        "DefaultSenderDomain":"m.mydomainone.com",
        "DefaultSenderDomainMonthlyLimit":"35",
        "DefaultSenderDomainRemainingMonthlyQuota":35
      }

    },
    "MFA_QRCode": "https://example.com/mfa-qr-code",
    "MFA_SecretKey": "MFA123SECRET",
    "SubscriptionID": "123456789"
  },
  "Usage": {
    "EmailGateway_TotalSentThisMonth": 100,
    "EmailGateway_TotalSentAllTime": 1000,
    "Limit_Monthly": 500,
    "Limit_Lifetime": 10000
  },
  "SendRateLimits": {
    "EmailGateway": {
      "RateLimits": {
        "MaxSendPerMinute": 10,
        "MaxSendPerHour": 200,
        "MaxSendPerDay": 1000
      },
      "SendRates": {
        "CurrentSendRatePerMinute": 5,
        "CurrentSendRatePerHour": 150,
        "CurrentSendRatePerDay": 800
      }
    }
  }
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorMessage": "Invalid SessionID or APIKey"
}
txt
1: Invalid SessionID or APIKey
2: User not found
3: Access denied
4: Required parameter missing
5: Internal server error

Retrieve User Information

POST /api.php

This endpoint retrieves user information based on the provided email address or user ID.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandUser.GetYes
EmailAddressThe email address of the user to retrieve information for. Required if UserID is not provided.Conditional
UserIDThe unique identifier of the user to retrieve information for. Required if EmailAddress is not provided.Conditional
bash
curl -X POST https://example.com/api.php \
-H "Content-Type: application/json" \
-d '{
    "SessionID": "your-session-id",
    "APIKey": "your-api-key",
    "Command": "User.Get",
    "EmailAddress": "user@example.com"
}'
json
{
    "Success": true,
    "ErrorCode": 0,
    "UserInformation": {
        "UserID": "123",
        "FirstName": "John",
        "LastName": "Doe",
        "EmailAddress": "user@example.com",
        // Other user details
        "GroupInformation": {
          "UserGroupID":"2",
          "GroupName":"Test User Group",
          // Other user group details
          "Options": {
            // Other user group options
            "DefaultSenderDomain":"m.mydomainone.com",
            "DefaultSenderDomainMonthlyLimit":"35",
            "DefaultSenderDomainRemainingMonthlyQuota":35
          }
        }
    }
}
json
{
    "Success": false,
    "ErrorCode": [3]
}
txt
1: "EmailAddress is required when UserID is not provided."
2: "UserID is required when EmailAddress is not provided."
3: "User not found with the provided information."

User Authentication

POST /api.php

This endpoint is used for authenticating a user with a username and password or an API key. It supports both standard and email-based logins, as well as two-factor authentication (2FA) recovery.

Request Body Parameters:

ParameterDescriptionRequired?
CommandUser.LoginYes
UsernameThe username of the user trying to log inNo*
PasswordThe password of the user in plain textNo*
PasswordEncryptedSet to true if the password is already encrypted (MD5)No
DisableCaptchaSet to true to disable captcha verificationNo
CaptchaThe captcha value that needs to be verifiedNo*
TfaRecoveryCodeThe recovery code for users with 2FA enabledNo
Disable2faSet to true to disable 2FA verification for this login attemptNo
TfaCodeThe 2FA code from the user's authentication appNo

NOTE

(*) username and password are required unless an APIKey is provided. If disablecaptcha is not set to true, captcha is required.

bash
curl -X POST https://example.com/api.php \
  -d 'Command=User.Login' \
  -d 'username=johndoe' \
  -d 'password=examplePassword'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "SessionID": "newSessionId",
  "UserInfo": {
    "UserID": "123",
    "Username": "johndoe",
    "EmailAddress": "john@example.com",
    "AccountStatus": "Enabled",
    // Additional user info fields
    "Password": "****** masked ******"
  }
}
json
{
  "Success": false,
  "ErrorCode": [3],
  "ErrorText": ["Invalid login information"]
}
txt
1: Missing username
2: Missing password
3: Invalid login information
4: Missing or invalid captcha
5: Invalid captcha
6: Invalid 2FA code or recovery code

Update User Information

POST /api.php

This endpoint allows for updating user information. It can be used to modify various user details such as email address, username, personal information, and account settings. Some parameters can only be updated by an administrator.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandUser.UpdateYes
UserIDThe unique identifier of the user to updateYes
AccountStatusThe new status of the user's account (admin only)No
AvailableCreditsThe number of available credits for the user (admin only)No
SignUpIPAddressThe IP address from which the user signed up (admin only)No
APIKeyThe new API key for the user (admin only)No
RelUserGroupIDThe ID of the user group to which the user belongs (admin only)No
ReputationLevelThe reputation level of the user, either 'Trusted' or 'Untrusted' (admin only)No
UserSinceThe date since the user has been a member (admin only)No
EmailAddressThe new email address for the userNo
UsernameThe new username for the userNo
PasswordThe new password for the userNo
FirstNameThe user's first nameNo
LastNameThe user's last nameNo
CompanyNameThe name of the user's companyNo
WebsiteThe user's website URLNo
OtherEmailAddressesOther email addresses associated with the userNo
StreetThe user's street addressNo
Street2Additional street address information for the userNo
CityThe user's cityNo
StateThe user's state or regionNo
ZipThe user's postal or zip codeNo
CountryThe user's countryNo
VATThe user's VAT numberNo
PhoneThe user's phone numberNo
PhoneVerifiedWhether the user's phone number is verified (1 or 0)No
FaxThe user's fax numberNo
TimeZoneThe user's time zoneNo
LanguageThe user's preferred languageNo
LastActivityDateTimeThe last activity date and time for the userNo
ForwardToFriendHeaderCustom header for the 'Forward to Friend' emailsNo
ForwardToFriendFooterCustom footer for the 'Forward to Friend' emailsNo
PreviewMyEmailAccountThe account information for PreviewMyEmail integrationNo
PreviewMyEmailAPIKeyThe API key for PreviewMyEmail integrationNo
Enable2FAEnable two-factor authentication ('true' to enable)No
Cancel2FACancel two-factor authentication ('true' to cancel)No
RateLimitsCustom rate limits for the userNo
CustomEmailHeadersCustom email headers for the userNo
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=User.Update' \
  -d 'UserID=123' \
  -d 'EmailAddress=newemail@example.com'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": 2,
  "ErrorText": "User ID mismatch or unauthorized access."
}
txt
1: Missing required field(s).
2: User ID mismatch or unauthorized access.
3: Connection error occurred with PreviewMyEmail.com API.
4: Two-factor authentication code verification failed.
5: User information retrieval failed.
6: Email address or username already exists.

Delete Users

POST /api.php

This endpoint is used to delete one or more users from the system. The user IDs to be deleted are passed as a comma-separated list.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandUsers.DeleteYes
usersComma-separated list of user IDs to deleteYes
bash
curl -X POST https://yourapiendpoint.com/api.php \
-H "Content-Type: application/json" \
-d '{"SessionID": "your-session-id", "APIKey": "your-api-key", "Command": "Users.Delete", "users": "1,2,3"}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": {
    "users": "NOT AVAILABLE IN DEMO MODE"
  }
}
txt
NOT AVAILABLE IN DEMO MODE: The function is not available in demo mode.

Retrieve User List

POST /api.php

This endpoint retrieves a list of users based on various criteria such as user group, account status, reputation, or a specific search term.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandUsers.GetYes
RecordsPerRequestThe number of records to return per request. Defaults to 25 if not provided.No
RecordsFromThe starting point for records to return. Defaults to 0 if not provided.No
RelUserGroupIDThe ID of the user group to filter by. Can be an array for multiple groups.No
OrderFieldThe field to order the results by.No
OrderTypeThe order type (e.g., ASC, DESC).No
SearchFieldThe field to search within.No
SearchKeywordThe keyword to search for.No
bash
curl -X POST https://example.com/api.php \
-H "Content-Type: application/json" \
-d '{
    "SessionID": "your-session-id",
    "APIKey": "your-api-key",
    "Command": "Users.Get",
    "RecordsPerRequest": 10,
    "RecordsFrom": 0,
    "RelUserGroupID": "Online",
    "OrderField": "LastName",
    "OrderType": "ASC",
    "SearchField": "FirstName",
    "SearchKeyword": "John"
}'
json
{
    "Success": true,
    "ErrorCode": 0,
    "Users": [
        {
            "UserID": 1,
            "FirstName": "John",
            "LastName": "Doe",
            "Email": "john.doe@example.com",
            // Additional user fields...
        }
        // More users...
    ],
    "TotalUsers": 100
}
json
{
    "Success": false,
    "ErrorCode": 1,
    "ErrorMessage": "An error occurred while retrieving the user list."
}
txt
1: An error occurred while retrieving the user list.

Create User API Key

POST api/v1/user.apikey

This endpoint is used to create a new API key for a user. It requires an administrative note and optionally allows binding to an IP address.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
NoteAn administrative note for the API keyYes
BoundIpAddressIP address to bind the API key to (optional)No
bash
curl -X POST 'https://example.com/api/v1/user.apikey' \
-H 'Content-Type: application/json' \
-d '{
    "SessionID": "your_session_id",
    "APIKey": "your_api_key",
    "note": "Administrative note for API key",
    "boundipaddress": "192.168.1.1"
}'
json
{
    "APIKeyID": "generated_api_key_id",
    "APIKey": {
        "Key": "generated_api_key",
        "Note": "Administrative note for API key",
        "BoundIPAddress": "192.168.1.1"
    }
}
json
{
    "Errors": [
        {"Code": 1, "Message": "Missing administrative note parameter"},
        {"Code": 3, "Message": "API key create process failed"},
        {"Code": 4, "Message": "New API key create process has failed"}
        // ... other possible error messages
    ]
}

HTTP Response and Error Codes:

HTTP Response CodeError CodeDescription
4221Missing administrative note parameter
4222Missing administrative bound IP address parameter (if applicable)
4003API key create process failed
4044New API key create process has failed

Delete User API Key

POST api/v1/user.apikey.delete

This endpoint allows for the deletion of a specific API key associated with a user. It requires the unique identifier of the API key to be deleted.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
apikeyidThe unique identifier of the API key to deleteYes
bash
curl -X POST 'https://example.com/api/v1/user.apikey.delete' \
-H 'Content-Type: application/json' \
-d '{
    "SessionID": "your_session_id",
    "APIKey": "your_api_key",
    "apikeyid": "api_key_id_to_delete"
}'
json
{
    "Success": true
}
json
{
    "Errors": [
        {"Code": 1, "Message": "Missing APIKeyID parameter"},
        {"Code": 2, "Message": "API key not found"}
        // ... other possible error messages
    ]
}
text
1: Missing APIKeyID parameter
2: API key not found

HTTP Response and Error Codes:

HTTP Response CodeError CodeDescription
4221Missing APIKeyID parameter
4042API key not found

Based on the PHP code for the "GET api/v1/user.apikeys" endpoint, I will create an API documentation template. This endpoint is used for retrieving all API keys associated with a user.


Retrieve User API Keys

GET api/v1/user.apikeys

This endpoint provides a list of all API keys associated with the current user. It does not require any additional parameters apart from the user's session and API key.

Request Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
bash
curl 'https://example.com/api/v1/user.apikeys' \
-H 'Content-Type: application/json' \
-d '{
    "SessionID": "your_session_id",
    "APIKey": "your_api_key"
}'
json
{
    "Success": true,
    "APIKeys": [
        {
            "APIKeyID": "api_key_id_1",
            "APIKey": "api_key_value_1",
            "Note": "Administrative note for API key 1",
            "BoundIPAddress": "192.168.1.1"
        },
        // ... more API keys
    ]
}
json
{
    "Errors": [
    ]
}

HTTP Response and Error Codes:

This endpoint does not have specific error codes defined.

Any questions? Contact us.