Settings API Documentation

System settings management endpoints for configuring Octeth application settings and testing email delivery configurations.

Test Email Sending Configuration

POST /api/v1/settings.emailsendingtest

API Usage Notes

Authentication required: Admin API Key
v1 REST alias: POST /api/v1/settings.emailsendingtest. Legacy access via /api.php is also supported

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: `settings.emailsendingtest`
SessionID	String	No	Session ID obtained from login
APIKey	String	No	Admin API key for authentication
SendMethod	String	No	Email sending method: `SMTP`, `LocalMTA`, `PHPMail`, `PowerMTA`, or `SaveToDisk`
SendMethodSMTPHost	String	No	SMTP server hostname (required for SMTP method)
SendMethodSMTPPort	Integer	No	SMTP server port (required for SMTP method)
SendMethodSMTPSecure	String	No	SMTP encryption: `ssl`, `tls`, or empty string
SendMethodSMTPAuth	String	No	SMTP authentication enabled: `true` or `false`
SendMethodSMTPUsername	String	No	SMTP username (required if auth is enabled)
SendMethodSMTPPassword	String	No	SMTP password (required if auth is enabled)
SendMethodSMTPTimeout	Integer	No	SMTP connection timeout in seconds
SendMethodLocalMTAPath	String	No	Local MTA path (required for LocalMTA method)
SendMethodPowerMTADir	String	No	PowerMTA directory path (required for PowerMTA method)
SendMethodSaveToDiskDir	String	No	Save to disk directory path (required for SaveToDisk method)
MailEngine	String	No	Mail engine: `phpmailer` or `swiftmailer`

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "settings.emailsendingtest",
    "SessionID": "your-admin-session-id",
    "SendMethod": "SMTP",
    "SendMethodSMTPHost": "smtp.example.com",
    "SendMethodSMTPPort": 587,
    "SendMethodSMTPSecure": "tls",
    "SendMethodSMTPAuth": "true",
    "SendMethodSMTPUsername": "smtp-user@example.com",
    "SendMethodSMTPPassword": "smtp-password",
    "SendMethodSMTPTimeout": 30,
    "MailEngine": "phpmailer"
  }'

json

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

json

{
  "Success": false,
  "ErrorCode": 1,
  "EmailSettingsErrorMessage": "SMTP connect() failed"
}

txt

0: Success
1: Email sending test failed (check EmailSettingsErrorMessage for details)
2: Invalid enum value (SendMethod, SendMethodSMTPSecure, SendMethodSMTPAuth, or MailEngine)
3: SendMethodLocalMTAPath is not a valid local MTA path (v6.0.0, LocalMTA only)
NOT AVAILABLE IN DEMO MODE: Endpoint disabled in demo mode

Behavior change (v6.0.0): the local MTA path is validated

The path that names the local mail submission binary was previously accepted verbatim and handed to the operating system, so a value containing a space was treated as a command with arguments rather than as a single path.

A valid path is now absolute, contains no whitespace, control characters or shell metacharacters, has no relative or empty segment, names a file that exists on the server and is executable by the web server user, and has a file name containing one of sendmail, qmail, smtp, exim, postfix, mta or mail. So sendmail, sendmail.postfix, qmail-inject, ssmtp, msmtp, exim4 and mini_sendmail all qualify.

settings.emailsendingtest sends rather than saves, so when SendMethod is LocalMTA it needs a real executable path and an empty one is refused with ErrorCode 3, like any other value that cannot be run. The check applies only when SendMethod is LocalMTA; a test over any other method ignores the field. Sending with an empty local MTA path was never possible, and that has not changed.

The same rule applies when the path is saved, on settings.update (ErrorCode 22) and on usergroup.create, usergroup.update and usergroup.patch (ErrorCode 35), where an empty value stays valid because it is the shipped default and the admin screens post the field on every save whatever the send method.

Sending is also checked at the point of use on both mail engines, so a path stored before this release is refused rather than run: the message is not sent, the failure is reported to whatever asked for the send, and the reason is logged once per distinct path.

:::

Get System Settings

GET /api/v1/settings.get

API Usage Notes

Authentication required: Admin API Key (privilege Settings)
v1 REST alias: GET /api/v1/settings.get. Legacy access via /api.php is also supported
Read counterpart of settings.update. Column names come from the oempro_config row itself, so a column added in a later version appears here without a client change.

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: `settings.get`
SessionID	String	No	Session ID obtained from login
APIKey	String	No	Admin API key for authentication
Keys	String	No	Comma-separated list of `oempro_config` column names and/or runtime option names to return (case-insensitive). Unknown names are an error. Omit for everything.

Response:

Settings: the oempro_config row keyed by column name (all columns except ConfigID). Values are typed the way the application types them at bootstrap: the stored strings true and false come back as JSON booleans, everything else as stored. Secrets (*_PASSWORD, S3_SECRET_KEY, and every other key matching the system.getsettings sensitive-key rule) are returned as the literal ***REDACTED*** when set, and as "" when empty. Sending that literal back to settings.update is refused (ErrorCode 13): omit the field to keep the stored secret.
RuntimeOptions: the oempro_options keys settings.update can write, in their decoded shapes: SeedList, AliasList, RelayDomains, PreHeaderTextTemplate, EmailDeliverySubscriberSnapshot, DefaultCustomFieldsForNewLists, FailedWebhookHandler, LimitUtilizationWebhook, Stripo_PluginId, Stripo_SecretKey, Stripo_APIKey, Unlayer_ProjectId, Unlayer_APIKey, MediaUploadStatus, MediaLibraryAllowedFileTypes (strings, null when never saved); ListFreshnessThresholds ({Active, SlowingDown, Stale} integers, defaulted like the Preferences screen); FailedWebhookHandlerSettings ({FailThreshold, DisableForXSeconds, CallWebhookURL}); LimitUtilizationWebhookSettings ({WebhookURL, NotifyTransitions{OKToWarning, WarningToExceeded, OKToExceeded, ExceededToWarning, WarningToOK, ExceededToOK}}); PreventUserLoginFromAlienIPs and DisableUserPasswordReset (booleans). Secrets are redacted the same way.

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "settings.get",
    "APIKey": "your-admin-api-key",
    "Keys": "PRODUCT_NAME,SEND_METHOD_SMTP_PASSWORD,ListFreshnessThresholds"
  }'

json

{
  "Success": true,
  "ErrorCode": 0,
  "Settings": {
    "PRODUCT_NAME": "Octeth",
    "SEND_METHOD_SMTP_PASSWORD": "***REDACTED***"
  },
  "RuntimeOptions": {
    "ListFreshnessThresholds": {"Active": 14, "SlowingDown": 45, "Stale": 90}
  }
}

json

{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "Unknown setting key(s): PRODUCT_NAM",
  "UnknownKeys": ["PRODUCT_NAM"]
}

txt

0: Success
1: One or more Keys are not a config column or a runtime option (see UnknownKeys)
2: The configuration row could not be read

Update System Settings

POST /api/v1/settings.update

API Usage Notes

Authentication required: Admin API Key
v1 REST alias: POST /api/v1/settings.update. Legacy access via /api.php is also supported

Request Body Parameters:

All parameters are optional. Only provide the settings you want to update.

Behavior change (v5.9.3, #2345)

Omitted parameters are now left unchanged. In earlier versions, a partial settings.update unconditionally overwrote DisableUserPasswordReset, MediaUploadStatus, and MediaLibraryAllowedFileTypes even when they were not sent. Updating only, say, SystemEmailFromName therefore silently re-enabled user password reset and blanked the media-upload settings. These three fields are now written only when included in the request.

Partial updates, null and the redaction marker

Omitted parameters are left unchanged. A JSON null value is treated as omitted (a silent no-op); to clear a setting send the empty string "".
settings.get returns secrets as the literal ***REDACTED***. Sending that literal as a value is refused with ErrorCode 13. Omit the field to keep the stored secret.
DEFAULT_LANGUAGE and USER_SIGNUP_LANGUAGE must name an installed language pack (system.languages.get), USER_SIGNUP_GROUPID / USER_SIGNUP_GROUPIDS must name existing user groups, and DEFAULT_THEMEID must name an existing theme. Empty values are still accepted.

Parameter	Type	Required	Description
Command	String	Yes	API command: `settings.update`
SessionID	String	No	Session ID obtained from login
APIKey	String	No	Admin API key for authentication
SystemEmailFromName	String	No	Default sender name for system emails
SystemEmailFromEmail	String	No	Default sender email address (email validation)
SystemEmailReplyToName	String	No	Default reply-to name
SystemEmailReplyToEmail	String	No	Default reply-to email address (email validation)
AlertRecipientEmail	String	No	Email address for system alerts (email validation)
ReportAbuseEmail	String	No	Email address for abuse reports (email validation)
XComplaintsTo	String	No	X-Complaints-To header value (email or @%sender_domain%)
MediaUploadMethod	String	No	Media upload method: `file`, `database`, or `s3`
MediaUploadStatus	String	No	Media upload status
MediaLibraryAllowedFileTypes	String	No	Allowed file types for media library
S3Enabled	String	No	Enable S3 storage: `true` or `false`
S3AccessID	String	No	AWS S3 access key ID
S3SecretKey	String	No	AWS S3 secret access key
S3Bucket	String	No	AWS S3 bucket name
S3MediaLibraryPath	String	No	S3 path for media library
S3URL	String	No	S3 bucket URL
LoadBalanceStatus	String	No	Enable load balancing: `true` or `false`
LoadBalanceEmails	Integer	No	Number of emails for load balancing
LoadBalanceSleep	Integer	No	Sleep interval for load balancing
UserSignupEnabled	String	No	Enable user signup: `true` or `false`
UserSignupFields	String	No	User signup form fields
UserSignupReputation	String	No	User signup reputation: `Trusted` or `Untrusted`
UserSignupLanguage	String	No	Default language for new users
DefaultLanguage	String	No	System default language
UserSignupGroupID	Integer	No	Default user group ID for signups
UserSignupGroupIDs	String	No	Multiple user group IDs for signups
DefaultThemeID	Integer	No	Default theme ID
PaymentCurrency	String	No	Payment currency code
PaymentTaxPercent	Number	No	Tax percentage for payments
PaymentReceiptEmailSubject	String	No	Payment receipt email subject
PaymentReceiptEmailMessage	String	No	Payment receipt email message
EnabledPlugins	String	No	Comma-separated codes of the plugins to mark enabled. Every code must be installed (see `admin.plugins.get`) and no code may repeat. This only writes the column: it does NOT run the plugins' `enable_<code>()` / `disable_<code>()` lifecycle hooks (table creation, option seeding, teardown). Use `admin.plugin.enable` / `admin.plugin.disable` to enable or disable a plugin.
SendMethod	String	No	Email sending method: `SMTP`, `LocalMTA`, `PHPMail`, `PowerMTA`, or `SaveToDisk`
SendMethodLocalMTAPath	String	No	Local MTA path
SendMethodPowerMTAVMTA	String	No	PowerMTA VMTA name
SendMethodPowerMTADir	String	No	PowerMTA directory path
SendMethodSaveToDiskDir	String	No	Save to disk directory path
SendMethodSMTPHost	String	No	SMTP server hostname
SendMethodSMTPPort	Integer	No	SMTP server port
SendMethodSMTPSecure	String	No	SMTP encryption: `ssl`, `tls`, or empty string
SendMethodSMTPAuth	String	No	SMTP authentication: `true` or `false`
SendMethodSMTPUsername	String	No	SMTP username
SendMethodSMTPPassword	String	No	SMTP password
SendMethodSMTPTimeout	Integer	No	SMTP timeout in seconds
SendMethodSMTPDebug	String	No	SMTP debug mode
SendMethodSMTPKeepAlive	String	No	SMTP keep-alive setting
SendMethodSMTPMsgConn	Integer	No	SMTP messages per connection
ImportMaxFilesize	Integer	No	Maximum file size for imports (bytes)
AttachmentMaxFilesize	Integer	No	Maximum attachment file size (bytes)
MediaMaxFilesize	Integer	No	Maximum media file size (bytes)
XMailer	String	No	X-Mailer header value
MailEngine	String	No	Mail engine: `phpmailer` or `swiftmailer`
GoogleAnalyticsSource	String	No	Google Analytics source parameter
GoogleAnalyticsMedium	String	No	Google Analytics medium parameter
ForwardToFriendHeader	String	No	Forward-to-friend email header
ForwardToFriendFooter	String	No	Forward-to-friend email footer
ReportAbuseFriendHeader	String	No	Report abuse email header
ReportAbuseFriendFooter	String	No	Report abuse email footer
UserSignupHeader	String	No	User signup email header
UserSignupFooter	String	No	User signup email footer
ProductName	String	No	Product name for branding
DefaultSubscriberAreaLogoutURL	String	No	Subscriber area logout redirect URL
POP3BounceStatus	String	No	Enable POP3 bounce processing: `Enabled` or `Disabled`
POP3BounceHost	String	No	POP3 bounce server hostname
POP3BouncePort	Integer	No	POP3 bounce server port
POP3BounceUsername	String	No	POP3 bounce username
POP3BouncePassword	String	No	POP3 bounce password
POP3BounceSSL	String	No	POP3 bounce SSL: `Yes` or `No`
POP3FBLStatus	String	No	Enable POP3 FBL processing: `Enabled` or `Disabled`
POP3FBLHost	String	No	POP3 FBL server hostname
POP3FBLPort	Integer	No	POP3 FBL server port
POP3FBLUsername	String	No	POP3 FBL username
POP3FBLPassword	String	No	POP3 FBL password
POP3FBLSSL	String	No	POP3 FBL SSL: `Yes` or `No`
POP3RequestsStatus	String	No	Enable POP3 request processing: `Enabled` or `Disabled`
POP3RequestsHost	String	No	POP3 requests server hostname
POP3RequestsPort	Integer	No	POP3 requests server port
POP3RequestsUsername	String	No	POP3 requests username
POP3RequestsPassword	String	No	POP3 requests password
POP3RequestsSSL	String	No	POP3 requests SSL: `Yes` or `No`
SendBounceNotificationEmail	String	No	Email address for bounce notifications
RebrandedProductLogo	String	No	Custom product logo
RebrandedProductLogoType	String	No	Product logo type
PayPalExpressStatus	String	No	PayPal Express status: `Enabled` or `Disabled`
PayPalExpressBusinessName	String	No	PayPal business name
PayPalExpressPurchaseDescription	String	No	PayPal purchase description
PayPalExpressCurrency	String	No	PayPal currency code
DisplayTriggerSendEngineLink	String	No	Display send engine link: `Yes` or `No`
DefaultOptinEmailSubject	String	No	Default opt-in confirmation email subject
DefaultOptinEmailBody	String	No	Default opt-in confirmation email body (must include %Link:Confirm%)
UserareaFooter	String	No	User area footer content
ForbiddenFromAddresses	String	No	Forbidden sender email addresses
RunCronInUserArea	String	No	Run cron in user area: `true` or `false`
CentralizedSenderDomain	String	No	Centralized sender domain
PaymentCreditsGatewayURL	String	No	Payment credits gateway URL
AdminAllowedIP	String	No	Allowed IP addresses for admin access
RateLimitExceedSlackWebhookURL	String	No	Slack webhook for rate limit alerts
RateLimitExceedNotificationInterval	Integer	No	Rate limit notification interval
DisableUserPasswordReset	String	No	Disable user password reset: `true` or `false`
DisplayOriginalLogo	String	No	Display original logo: `Yes` or `No`
FBLIncomingEmailAddress	String	No	FBL incoming email address
UnsubscribeIncomingEmailAddress	String	No	Unsubscribe incoming email address
BounceForwardTo	String	No	Bounce forward-to email address
ThresholdSoftBounceDetection	Integer	No	Soft bounce detection threshold
BounceCatchAllDomain	String	No	Bounce catch-all domain
S2STrackerParam	String	No	S2S postback tracker parameter name (1 to 20 characters: letters, digits, `_`, `-`)
S2SChannelParam	String	No	S2S postback conversion channel parameter name (same rule)
S2SValueParam	String	No	S2S postback conversion value parameter name (same rule)
S2SUnitParam	String	No	S2S postback conversion unit parameter name (same rule)
SeedList	String	No	Newline-separated seed addresses; every non-blank line must be a valid email address
AliasList	String	No	Newline-separated alias list (bounce server)
RelayDomains	String	No	Newline-separated relay domains (bounce server)
PreHeaderTextTemplate	String	No	Pre-header text template
EmailDeliverySubscriberSnapshot	String	No	`Enabled` or `Disabled`
ListFreshnessThresholds	Object	No	`{Active, SlowingDown, Stale}` in days; normalised so that Active >= 1 and Active < SlowingDown < Stale (each later value is raised to previous + 1 if needed); missing keys take the defaults 14 / 45 / 90. Also accepted as a JSON string.
DefaultCustomFieldsForNewLists	String	No	Default custom fields for new lists
FailedWebhookHandler	String	No	`Enabled` or `Disabled`
FailedWebhookHandlerSettings	Object	No	`{FailThreshold (int >= 1, default 3), DisableForXSeconds (int >= 0, default 3600), CallWebhookURL (URL or empty)}`. Also accepted as a JSON string.
LimitUtilizationWebhook	String	No	`Enabled` or `Disabled`. When the effective value is `Enabled`, at least one `NotifyTransitions` flag must be true (the request value, else the stored one)
LimitUtilizationWebhookSettings	Object	No	`{WebhookURL (URL or empty), NotifyTransitions{OKToWarning, WarningToExceeded, OKToExceeded, ExceededToWarning, WarningToOK, ExceededToOK}}`; flags accept true/false, 1/0, "true"/"false"; missing flags are false. Also accepted as a JSON string.
PreventUserLoginFromAlienIPs	Boolean	No	`true` stores the flag, `false` removes it (the stored representation the Security screen uses)
Stripo_PluginId	String	No	Stripo plugin id. When the effective plugin id / secret key pair is non-empty (request value, else stored), the pair is verified live against Stripo before saving
Stripo_SecretKey	String	No	Stripo secret key (see above)
Stripo_APIKey	String	No	Stripo per-account API key list as a JSON-encoded STRING (a nested object is refused, because request keys are lowercased). Must be valid JSON and must fit the storage column (issue #1311). Empty clears.
Unlayer_ProjectId	String	No	Unlayer project id
Unlayer_APIKey	String	No	Unlayer API key

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "settings.update",
    "SessionID": "your-admin-session-id",
    "SystemEmailFromName": "My Company",
    "SystemEmailFromEmail": "noreply@mycompany.com",
    "SendMethod": "SMTP",
    "SendMethodSMTPHost": "smtp.example.com",
    "SendMethodSMTPPort": 587,
    "SendMethodSMTPSecure": "tls",
    "SendMethodSMTPAuth": "true",
    "SendMethodSMTPUsername": "smtp-user@example.com",
    "SendMethodSMTPPassword": "smtp-password",
    "UserSignupEnabled": "true",
    "UserSignupEnabled": "true"
  }'

json

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

json

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

txt

0: Success
1: Invalid email address
2: Invalid enum value (MediaUploadMethod, S3Enabled, LoadBalanceStatus, UserSignupEnabled, UserSignupReputation, SendMethod, SendMethodSMTPSecure, SendMethodSMTPAuth, MailEngine, or RunCronInUserArea)
3: PreviewMyEmail API connection error
6: POP3/IMAP connection failed (check EmailSettingsErrorMessage for details)
7: Default opt-in email body missing required %Link:Confirm% tag
8: DEFAULT_LANGUAGE / USER_SIGNUP_LANGUAGE is not an installed language pack
9: USER_SIGNUP_GROUPID / USER_SIGNUP_GROUPIDS names a user group that does not exist (or is not an id list)
10: DEFAULT_THEMEID does not name an existing theme
11: An S2S parameter name is empty, longer than 20 characters, or contains characters other than letters, digits, underscore and dash
12: SeedList contains an invalid email address (see InvalidEntries)
13: A value is the redaction marker ***REDACTED*** (omit the field to keep the stored value)
14: ListFreshnessThresholds is not an object
22: SEND_METHOD_LOCALMTA_PATH is not a valid local MTA path (v6.0.0; an empty value is accepted)
15: FailedWebhookHandlerSettings is invalid (see ErrorText)
16: LimitUtilizationWebhookSettings is invalid, or the webhook is Enabled with no NotifyTransitions flag set
17: Stripo rejected the plugin id / secret key pair
18: Stripo_APIKey is not a JSON-encoded string
19: Stripo_APIKey exceeds the storage column capacity (see ErrorText)
20: EnabledPlugins names a plugin that is not installed
21: EnabledPlugins lists a plugin more than once
NOT AVAILABLE IN DEMO MODE: Endpoint disabled in demo mode

Behavior change (v6.0.0): the PayPal Express fields are no longer accepted

settings.update no longer accepts PAYPALEXPRESSSTATUS, PAYPALEXPRESSBUSINESSNAME, PAYPALEXPRESSPURCHASEDESCRIPTION or PAYPALEXPRESSCURRENCY, because the built-in PayPal Express Checkout gateway has been removed. Sending one is ignored rather than refused, exactly as for any other unrecognised field, so an existing integration does not start returning errors. It simply no longer changes anything.

settings.get and system.getsettings still return those values, because the columns remain on the configuration table and no migration drops them. They are historical data and nothing in the product reads them. See Behavior changes in v6.0.0 for what to use instead.

Get Delivery Routes

GET /api/v1/deliveryroutes.get

API Usage Notes

Authentication required: Admin API Key (privilege Settings)
v1 REST alias: GET /api/v1/deliveryroutes.get. Legacy access via /api.php is also supported
The recipient MX to delivery-server routing map (admin Settings > Delivery Routes). Each entry's Pattern is either an exact MX host name or a PCRE pattern (the delivery workers try preg_match first, then an exact comparison). Entries are an ordered list: the first match wins.

Request Body Parameters:

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

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"Command": "deliveryroutes.get", "APIKey": "your-admin-api-key"}'

json

{
  "Success": true,
  "ErrorCode": 0,
  "Routes": [
    {"Pattern": "/\\.google\\.com$/i", "DeliveryServerID": 3},
    {"Pattern": "mx1.example.net", "DeliveryServerID": 5}
  ],
  "TotalRoutes": 2
}

json

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

txt

0: Success

Update Delivery Routes

POST /api/v1/deliveryroutes.update

API Usage Notes

Authentication required: Admin API Key (privilege Settings)
v1 REST alias: POST /api/v1/deliveryroutes.update. Legacy access via /api.php is also supported
Replaces the WHOLE routing map. Send the complete list every time; an empty list clears it. Order is significant.
Pattern values are stored verbatim. Do not send the map as a JSON object keyed by pattern: request object keys are lowercased, which would rewrite a PCRE pattern.
Written through the cached options writer, so the delivery workers pick the change up immediately.

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: `deliveryroutes.update`
SessionID	String	No	Session ID obtained from login
APIKey	String	No	Admin API key for authentication
Routes	Array	Yes	Ordered list of `{Pattern, DeliveryServerID}` objects (or a JSON string encoding one). `Pattern`: non-empty, no whitespace. `DeliveryServerID`: an existing delivery server. Patterns must be unique.

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "deliveryroutes.update",
    "APIKey": "your-admin-api-key",
    "Routes": [
      {"Pattern": "/\\.google\\.com$/i", "DeliveryServerID": 3},
      {"Pattern": "mx1.example.net", "DeliveryServerID": 5}
    ]
  }'

json

{
  "Success": true,
  "ErrorCode": 0,
  "Routes": [
    {"Pattern": "/\\.google\\.com$/i", "DeliveryServerID": 3},
    {"Pattern": "mx1.example.net", "DeliveryServerID": 5}
  ],
  "TotalRoutes": 2
}

json

{
  "Success": false,
  "ErrorCode": 5,
  "ErrorText": "Routes[2]: delivery server 99 does not exist."
}

txt

0: Success
1: Routes is missing
2: Routes is not a list of objects (also: an element that is not a {Pattern, DeliveryServerID} object; the {"pattern": id} map shape is only accepted when Routes is sent as a JSON string, since nested object keys are lowercased on the way in)
3: A Pattern is empty or contains whitespace
4: A DeliveryServerID is not a positive integer
5: A DeliveryServerID does not exist
6: A Pattern appears more than once
NOT AVAILABLE IN DEMO MODE: Endpoint disabled in demo mode

Get SMS Settings

GET /api/v1/sms.settings.get

API Usage Notes

Authentication required: Admin API Key (privilege SMS)
v1 REST alias: GET /api/v1/sms.settings.get. Legacy access via /api.php is also supported
The three settings of admin Settings > SMS.

Request Body Parameters:

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

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"Command": "sms.settings.get", "APIKey": "your-admin-api-key"}'

json

{
  "Success": true,
  "ErrorCode": 0,
  "SmsSettings": {
    "FrequencyLimits": {"Daily": 5, "Weekly": 10, "Monthly": 20, "Yearly": 100},
    "ForbiddenWords": "word1\nword2",
    "FrequencyWhitelistedNumbers": "+15551234567"
  }
}

json

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

txt

0: Success

Update SMS Settings

POST /api/v1/sms.settings.update

API Usage Notes

Authentication required: Admin API Key (privilege SMS)
v1 REST alias: POST /api/v1/sms.settings.update. Legacy access via /api.php is also supported
Partial update: omitted parameters are left unchanged. At least one must be sent.

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: `sms.settings.update`
SessionID	String	No	Session ID obtained from login
APIKey	String	No	Admin API key for authentication
FrequencyLimits	Object	No	`{Daily, Weekly, Monthly, Yearly}`, all four required, non-negative integers. Also accepted as a JSON string.
ForbiddenWords	String	No	Newline-separated forbidden words
FrequencyWhitelistedNumbers	String	No	Newline-separated numbers exempt from the frequency limits

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "sms.settings.update",
    "APIKey": "your-admin-api-key",
    "FrequencyLimits": {"Daily": 5, "Weekly": 10, "Monthly": 20, "Yearly": 100},
    "ForbiddenWords": "word1\nword2"
  }'

json

{
  "Success": true,
  "ErrorCode": 0,
  "UpdatedKeys": ["sms_frequency_limits", "sms_forbidden_words"]
}

json

{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "FrequencyLimits: Yearly must be a non-negative integer"
}

txt

0: Success
1: FrequencyLimits is invalid (see ErrorText)
2: ForbiddenWords / FrequencyWhitelistedNumbers is not a string
3: Nothing to update
NOT AVAILABLE IN DEMO MODE: Endpoint disabled in demo mode

List Email Headers

GET /api/v1/emailheaders.get

API Usage Notes

Authentication required: Admin API Key (privilege Settings)
v1 REST alias: GET /api/v1/emailheaders.get. Legacy access via /api.php is also supported
System-wide custom email headers (admin Settings > Email Delivery > Headers). DeliveryServerID 0 means the header applies on every delivery server.

Request Body Parameters:

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

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"Command": "emailheaders.get", "APIKey": "your-admin-api-key"}'

json

{
  "Success": true,
  "ErrorCode": 0,
  "EmailHeaders": [
    {"HeaderID": 1, "Name": "X-Campaign-Source", "Value": "octeth", "EmailType": "campaign", "DeliveryServerID": 0}
  ],
  "TotalEmailHeaders": 1
}

json

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

txt

0: Success

Create Email Header

POST /api/v1/emailheader.create

API Usage Notes

Authentication required: Admin API Key (privilege Settings)
v1 REST alias: POST /api/v1/emailheader.create. Legacy access via /api.php is also supported

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: `emailheader.create`
SessionID	String	No	Session ID obtained from login
APIKey	String	No	Admin API key for authentication
Name	String	Yes	Header field name: letters, digits and the punctuation `!#$%&'*+.^_~-`, plus the backtick and the vertical bar (RFC 5322 field-name characters)
Value	String	Yes	Header value, one line
EmailType	String	No	`all` (default), `campaign`, `autoresponder` or `transactional`
DeliveryServerID	Integer	No	Restrict the header to one delivery server; `0` (default) applies it everywhere

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "emailheader.create",
    "APIKey": "your-admin-api-key",
    "Name": "X-Campaign-Source",
    "Value": "octeth",
    "EmailType": "campaign"
  }'

json

{
  "Success": true,
  "ErrorCode": 0,
  "EmailHeader": {"HeaderID": 7, "Name": "X-Campaign-Source", "Value": "octeth", "EmailType": "campaign", "DeliveryServerID": 0}
}

json

{
  "Success": false,
  "ErrorCode": 5,
  "ErrorText": "EmailType must be one of all, campaign, autoresponder, transactional."
}

txt

0: Success
1: Name is missing
2: Value is missing
3: Name is not a valid header field name
4: Value is empty or spans more than one line
5: EmailType is not one of the four values
6: DeliveryServerID is not a non-negative integer
7: DeliveryServerID does not exist
NOT AVAILABLE IN DEMO MODE: Endpoint disabled in demo mode

Delete Email Headers

POST /api/v1/emailheaders.delete

API Usage Notes

Authentication required: Admin API Key (privilege Settings)
v1 REST alias: POST /api/v1/emailheaders.delete. Legacy access via /api.php is also supported
Ids that do not exist are reported in MissingHeaderIDs; the others are still deleted.

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: `emailheaders.delete`
SessionID	String	No	Session ID obtained from login
APIKey	String	No	Admin API key for authentication
HeaderIDs	String	Yes	Comma-separated header ids (an array is also accepted)

Example RequestSuccess ResponseError ResponseError Codes

bash

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"Command": "emailheaders.delete", "APIKey": "your-admin-api-key", "HeaderIDs": "7,8"}'

json

{
  "Success": true,
  "ErrorCode": 0,
  "DeletedHeaderIDs": [7],
  "MissingHeaderIDs": [8]
}

json

{
  "Success": false,
  "ErrorCode": 2,
  "ErrorText": "HeaderIDs must be a comma-separated list of positive integers."
}

txt

0: Success
1: HeaderIDs is missing
2: HeaderIDs is not a list of positive integers
NOT AVAILABLE IN DEMO MODE: Endpoint disabled in demo mode

Settings API Documentation ​

Test Email Sending Configuration ​

Get System Settings ​

Update System Settings ​

Get Delivery Routes ​

Update Delivery Routes ​

Get SMS Settings ​

Update SMS Settings ​

List Email Headers ​

Create Email Header ​

Delete Email Headers ​

Settings API Documentation

Test Email Sending Configuration

Get System Settings

Update System Settings

Get Delivery Routes

Update Delivery Routes

Get SMS Settings

Update SMS Settings

List Email Headers

Create Email Header

Delete Email Headers