{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Provider Settings","description":"Developer documentation for the WHMCS API — the","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"provider-settings","__idx":0},"children":["Provider Settings"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Mail Provider can define required settings to activate the mail provider module."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The field definitions you return from this method are used to build a form in the admin user interface that must be filled out in order to activate the mail provider module."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, if the module connects to a remote messaging service, this might be a username and password or a required OAuth token to authenticate to that service."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported field types are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yesno"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dropdown"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["radio"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["textarea"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below is an example of two defined fields, with the names ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_username"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_password"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"/**\n * Provider settings.\n *\n * @return array\n */\npublic function settings()\n{\n    return [\n        'api_username' => [\n            'FriendlyName' => 'API Username',\n            'Type' => 'text',\n            'Description' => 'The required username to authenticate with messaging service.',\n        ],\n        'api_password' => [\n            'FriendlyName' => 'API Password',\n            'Type' => 'password',\n            'Description' => 'The required password to authenticate with messaging service.',\n        ],\n    ];\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validating-user-supplied-setting-values","__idx":1},"children":["Validating User-Supplied Setting Values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On submission of mail provider settings, you can validate the user-provided values using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["testConnection"]}," method."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If validation fails, throw an exception to abort the save action and display an error message to the end user. The error message will be the message within the exception."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"/**\n * Test connection.\n *\n * @param array $settings\n *\n * @return array\n */\npublic function testConnection($settings)\n{\n    $api_username = $settings['api_username'];\n    $api_password = $settings['api_password'];\n\n    // Attempt to connect to API service to verify input credentials\n    // and upon error, throw an exception.\n\n    throw new \\Exception('The system was unable to authenticate with the supplied API username and password.');\n}\n"},"children":[]}]},"headings":[{"value":"Provider Settings","id":"provider-settings","depth":1},{"value":"Validating User-Supplied Setting Values","id":"validating-user-supplied-setting-values","depth":2}],"frontmatter":{"title":"Provider Settings","seo":{"title":"Provider Settings"}},"lastModified":"2026-08-03T17:00:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/mail-providers/provider-settings","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}