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"
      "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",
    "GroupInformation": {
      "UserGroupID": "2",
      "GroupName": "Test 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",
    "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
WhiteListedEmailAddressesEmail addresses to whitelist. Each address should be on a separate line. Emails listed here will not be added to the suppression list, even in case of an opt-out request or hard bounce.No
DeliveryServerIDIn order to assign a different delivery server to the user, set the delivery server ID.No
DefaultSenderDomainIn order to assign a different default sender domain than user group's default sender domain, use this parameter. In order to activate user specific default sender domain, user group sender domain must also be enabled.No
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"
    }
  ],
  "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"
    }
  ]
}

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"
    }
  ]
}
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"
    }
  ]
}
json
{
  "Errors": [
  ]
}

HTTP Response and Error Codes:

This endpoint does not have specific error codes defined.

User Stats

GET api/v1/user.stats

This API endpoint allows users to retrieve their statistics for a specified period with optional aggregation by hours, days, weeks, months, or years. The response returns aggregated data over the specified period, along with overall statistics like the number of lists and active subscribers.

Request Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
StartDateThe start date of the period from which statistics should be retrieved. Format YYYY-MM-DD H:i:s.Yes
EndDateThe end date of the period up to which statistics should be retrieved. Format YYYY-MM-DD H:i:s.Yes
AggregationThe type of aggregation for the data. Possible values are: hourly, daily, weekly, monthly, yearlyYes
bash
curl -X POST https://example.com/api/v1/user.stats \
-H "Content-Type: application/json" \
-d '{
    "SessionID": "your_session_id",
    "StartDate": "2024-10-03 04:00:00",
    "EndDate": "2024-10-03 06:00:00",
    "Aggregation": "hourly"
}'
json
{
  "NumberOfLists": 16,
  "TotalActiveSubscribers": 49,
  "New Subscribers": {
    "2024-10-03 04:00:00": 69,
    "2024-10-03 05:00:00": 87,
    "2024-10-03 06:00:00": 26
  },
  "Lost Subscribers": {
    "2024-10-03 04:00:00": 4,
    "2024-10-03 05:00:00": 0,
    "2024-10-03 06:00:00": 93
  },
  "Sent Campaigns": {
    "2024-10-03 04:00:00": 53,
    "2024-10-03 05:00:00": 55,
    "2024-10-03 06:00:00": 31
  },
  "Sent Emails": {
    "2024-10-03 04:00:00": 73,
    "2024-10-03 05:00:00": 59,
    "2024-10-03 06:00:00": 91
  },
  "Opens": {
    "2024-10-03 04:00:00": 4,
    "2024-10-03 05:00:00": 77,
    "2024-10-03 06:00:00": 4
  },
  "Clicks": {
    "2024-10-03 04:00:00": 93,
    "2024-10-03 05:00:00": 95,
    "2024-10-03 06:00:00": 82
  },
  "Revenue": {
    "2024-10-03 04:00:00": 342525,
    "2024-10-03 05:00:00": 0,
    "2024-10-03 06:00:00": 20035
},
  "Hard Bounces": {
    "2024-10-03 04:00:00": 0,
    "2024-10-03 05:00:00": 0,
    "2024-10-03 06:00:00": 0
  },
  "Spam Complaints": {
    "2024-10-03 04:00:00": 0,
    "2024-10-03 05:00:00": 0,
    "2024-10-03 06:00:00": 0
  }
}
json
{
  "Errors": [
    {
      "Code": 6,
      "Message": "DateTime::__construct(): Failed to parse time string (2024-10-03 04:) at position 11 (0): Unexpected character"
    }
  ]
}
txt
1: Missing StartDate parameter. StartDate not provided in request.
2: Missing EndDate parameter. EndDate not provided in request.
3: Missing Aggregation parameter. Aggregation not provided in request.
4: Invalid Aggregation value. Aggregation has an invalid value, should be one of predefined types.
5: Unexpected error occurred. General error, can be customized for specific cases.
6: Exception message. Any internal server or logic error, such as invalid date format.

Any questions? Contact us.