Email Configuration Management

3 minute readReference

createEmailConfig

Creates a new email configuration.

You must specify configName.

Arguments Descriptions

configName

The name of your email configuration.

Argument type: String

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

mailFrom

(Optional) The email address used as the email sender address for notifications.

Argument type: String

mailHost

(Optional) The name of the email server host.

Argument type: String

mailPort

(Optional) The port number for the mail server, but may not need to be specified. The protocol software determines the default value (25 for SMTP and 465 for SSMTP). Specify a value for this argument when a non-default port is used.

Argument type: String

mailProtocol

(Optional) This is either SSMTP or SMTP (not case-sensitive). The default is SMTP.

mailUser

(Optional) This can be an individual or a generic name like "CloudBees CD/RO " — name of the email user on whose behalf CloudBees CD/RO sends email notifications.

Argument type: String

mailUserPassword

(Optional) Password for the email user who is sending notifications.

Argument type: String

Positional arguments

configName

Response

Returns an emailConfig element.

ec-perl

syntax: $cmdr->createEmailConfig(<configName>, {<optionals>});

Example

$cmdr->createEmailConfig("testConfiguration", {mailHost => "test-sol2", mailFrom => "test_user@abc.com", mailUser => "build@abc.com", mailUserPassword => "mybuildmail"});

ectool

syntax: ectool createEmailConfig <configName> …​

Example

ectool createEmailConfig EmailConfig_test --mailHost test-sol2 --mailFrom "test_user@abc.com" --mailUser "build@abc.com" --mailUserPassword "mybuildmail" --description "This is a test for the email config object"

deleteEmailConfig

Deletes an email configuration.

You must specify a configName.

Arguments Descriptions

configName

The name of the email configuration you want to delete.

Argument Type: String

Positional arguments

configName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteEmailConfig(<configName>);

Example

$cmdr->deleteEmailConfig("All users");

ectool

syntax: ectool deleteEmailConfig <configName>

Example

ectool deleteEmailConfig "All users"

getEmailConfig

Retrieves an email configuration by name.

You must specify a configName.

Arguments Descriptions

configName

The name of the email configuration.

Argument Type: String

Positional arguments

configName

Response

Returns one emailConfig element.

The mailUserPassword attribute value is not returned or displayed by the getEmailConfigs and getEmailConfig commands for security reasons.

ec-perl

syntax: $cmdr->getEmailConfig(<configName>);

Example

$cmdr->getEmailConfig("Config_test");

ectool

syntax: ectool getEmailConfig <configName>

Example

ectool getEmailConfig "Config_test"

getEmailConfigs

Retrieves all email configurations.

Arguments Descriptions

None

Positional arguments

None

Response

Returns one or more emailConfig elements.

NOTE:

  • The mailUserPassword attribute value is not returned or displayed by the getEmailConfigs and getEmailConfig commands for security reasons.

  • The configIndex attribute is managed internally by CloudBees CD/RO and cannot be used in any of the email configuration APIs. It is used internally to identify the order of emailConfig objects within the list.

ec-perl

syntax: $cmdr->getEmailConfigs();

Example

$cmdr->getEmailConfigs();

ectool

syntax: ectool getEmailConfigs

Example

ectool getEmailConfigs

modifyEmailConfig

Modifies an existing email configuration.

You must specify the configName.

Arguments Descriptions

configName

The name of your email configuration.

Argument Type: String

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>.

Argument Type: String

mailFrom

(Optional) The email address used as the email "sender" address for notifications.

Argument Type: String

mailHost

(Optional) The name of the email server host.

Argument Type: String

mailPort

(Optional) The port number for the mail server, but may not need to be specified. The protocol software determines the default value (25 for SMTP and 465 for SSMTP). Specify a value for this argument when a non-default port is used.

Argument Type: Integer

mailProtocol

(Optional) This is either SSMTP or SMTP (not case-sensitive). The default is SMTP.

Argument Type: String

mailUser

(Optional) The name of the email user, which can be an individual or a generic name such as "CloudBees CD/RO ".

Argument Type: String

mailUserPassword

(Optional) The password for the email user.

Argument Type: String

newName

(Optional) New name of the email configuration.

Argument Type: String

Positional arguments

configName

Response

Returns a modified emailConfig element.

ec-perl

syntax: $cmdr->modifyEmailConfig(<configName>, {<optionals>});

Example

$cmdr->modifyEmailConfig("QA test", {mailFrom => "test@example.com"});

ectool

syntax: ectool modifyEmailConfig <configName> [optionals]

Example

ectool modifyEmailConfig "QA test" --mailFrom "test@example.com" --description "This is a Secure SMTP email config object for testing"