MAS DevOps Ansible Collection Ansible CLI
Home Roles: Utilities smtp Role Variables Example Playbook License

smtp¤

Generate an SMTP configuration that can be directly applied to IBM Maximo Application Suite. The role supports the Twilio SendGrid email provider.

Prior to running this role, you must create an account with SendGrid. The SendGrid account needs to support creating subusers.

Tip

The role will generate a yaml file containing the definition of a Secret and SmtpCfg resource that can be used to configure the smtp email provider for MAS. This file can be directly applied using oc apply -f $MAS_CONFIG_DIR/smtp-$MAS_INSTANCE_ID.yml" or used in conjunction with the suite_config role.

This role will create a subuser that must be validated. An email with a validation link will be sent to the primary email address. You need to validate the subuser using this link. If validation fails, you can resend the email using the SendGrid admin UI.

Role Variables¤

Variable Required Default
smtp_type Yes None
mas_instance_id Yes None
mas_config_dir Yes None
mas_pod_templates_dir No None
custom_labels No None
sendgrid_primary_username Yes None
sendgrid_primary_email Yes None
sendgrid_primary_apikey Yes None
sendgrid_ips Yes None
sendgrid_subuser_username No ibm-mas_{mas_instance_id}
sendgrid_subuser_email Yes None
sendgrid_defaultrecipientemail Yes None
sendgrid_defaultsendername No Empty string
sendgrid_defaultshouldemailpasswords No false
sendgrid_configscope No system
sendgrid_hostname No smtp.sendgrid.net
sendgrid_port No 465
sendgrid_security No SSL
sendgrid_authentication No true
sendgrid_api_url No api.sendgrid.com
sendgrid_debug No False

SMTP Provider¤

smtp_type¤

SMTP email provider type for MAS email notifications — sendgrid is currently the only supported provider.

  • Required
  • Environment Variable: SMTP_TYPE
  • Default: None

Determines which SMTP provider configuration is created and which API endpoints are used. Requires an active SendGrid account with subuser support; future versions may support additional SMTP providers.

MAS Configuration¤

mas_instance_id¤

MAS instance identifier the SMTP configuration applies to — a valid MAS instance ID (e.g. prod, dev, masinst1).

  • Required
  • Environment Variable: MAS_INSTANCE_ID
  • Default: None

Must match the instance ID used during MAS installation. Used to name the generated SmtpCfg resource and in the default subuser username ibm-mas_{mas_instance_id}.

mas_config_dir¤

Local directory where the generated SMTP configuration files are saved — any valid local filesystem path (e.g. ~/masconfig, /opt/mas/config).

  • Required
  • Environment Variable: MAS_CONFIG_DIR
  • Default: None

The SmtpCfg YAML file (containing the Secret and SmtpCfg resources) is created as smtp-{mas_instance_id}.yml in this directory. Apply it manually with oc apply -f $MAS_CONFIG_DIR/smtp-$MAS_INSTANCE_ID.yml or use it with the suite_config role for automated configuration. Use a consistent directory across all MAS DevOps roles.

mas_pod_templates_dir¤

Directory containing pod template customizations for the SMTP service pods — must contain a file named ibm-mas-smtpcfg.yml.

  • Optional
  • Environment Variable: MAS_POD_TEMPLATES_DIR
  • Default: None

The pod template configuration is inserted into the SmtpCfg spec under the podTemplates element. See the BestEfforts reference and the Customizing Pod Templates documentation.

custom_labels¤

Custom key-value labels applied to the generated SMTP resources — comma-separated key=value pairs (e.g. environment=production,team=platform,cost-center=engineering).

  • Optional
  • Environment Variable: CUSTOM_LABELS
  • Default: None

Useful for resource organization, cost tracking, environment identification, and automation-driven resource discovery. Follow Kubernetes label naming conventions.

SendGrid Primary Account¤

sendgrid_primary_username¤

Username of the primary SendGrid account used to create the subuser for MAS email operations.

  • Required
  • Environment Variable: SENDGRID_PRIMARY_USERNAME
  • Default: None

The account must have permissions to create subusers. Primary account credentials are only used during setup and are not stored in MAS.

sendgrid_primary_email¤

Email address registered with the primary SendGrid account.

  • Required
  • Environment Variable: SENDGRID_PRIMARY_EMAIL
  • Default: None

Subuser validation emails are sent to this address — you must validate the subuser using the link in the email before it can send emails. The validation email can be resent from the SendGrid admin UI if needed.

sendgrid_primary_apikey¤

API key for the primary SendGrid account, with subuser creation and IP management permissions.

  • Required
  • Environment Variable: SENDGRID_PRIMARY_APIKEY
  • Default: None

Generate the key from the SendGrid console (Settings > API Keys). Store it securely and never commit it to version control; it is only used during setup for subuser creation and IP assignment, not stored in MAS configuration.

sendgrid_ips¤

SendGrid IP addresses to assign to the subuser — a JSON array string such as '["192.0.2.1", "192.0.2.2"]'.

  • Required
  • Environment Variable: SENDGRID_IPS
  • Default: None

The IPs must already be allocated to the primary account (find them in the SendGrid console: Settings > IP Addresses). The subuser sends emails from these addresses, so their reputation affects email deliverability.

SendGrid Subuser¤

sendgrid_subuser_username¤

Username for the SendGrid subuser created for MAS — alphanumeric, with hyphens and underscores allowed.

  • Optional
  • Environment Variable: SENDGRID_SUBUSER_USERNAME
  • Default: ibm-mas_{mas_instance_id}

Must be unique within the SendGrid account. Override the default if you need a specific naming convention or share one SendGrid account across multiple MAS instances. See the SendGrid subusers documentation.

sendgrid_subuser_email¤

Email address for the SendGrid subuser dedicated to sending MAS notifications — can be the same as or different from the primary account email.

  • Required
  • Environment Variable: SENDGRID_SUBUSER_EMAIL
  • Default: None

The subuser provides isolation from the primary account. See the SendGrid subusers documentation.

Email Defaults¤

sendgrid_defaultrecipientemail¤

Default recipient email address for MAS notifications when no specific recipient is configured — typically an admin or operations team email.

  • Required
  • Environment Variable: SENDGRID_DEFAULTRECIPIENTEMAIL
  • Default: None

Acts as the fallback for unconfigured notifications and can be overridden per notification type in MAS.

sendgrid_defaultsendername¤

Display name shown as the sender in email clients when MAS sends notifications — any string, e.g. MAS Notifications or Maximo Production.

  • Optional
  • Environment Variable: SENDGRID_DEFAULTSENDERNAME
  • Default: Empty string

Improves email recognition and trust; recommended for production deployments and can be left empty for default behavior.

sendgrid_defaultshouldemailpasswords¤

Controls whether MAS sends user passwords via email when creating or resetting accounts — true or false.

  • Optional
  • Environment Variable: SENDGRID_DEFAULTSHOULDEMAILPASSWORDS
  • Default: false

Warning

Sending passwords via email is generally not recommended — the default false follows security best practices. Only set to true if your security policy allows password transmission via email, and consider alternative password delivery methods.

sendgrid_configscope¤

Configuration scope for the SMTP settings — system is currently the only supported value.

  • Optional
  • Environment Variable: SENDGRID_CONFIGSCOPE
  • Default: system

System scope makes the SMTP configuration available to all MAS components; workspace or application scopes may be supported in future versions.

SMTP Connection¤

sendgrid_hostname¤

SendGrid SMTP server hostname that MAS connects to for sending emails.

  • Optional
  • Environment Variable: SENDGRID_HOSTNAME
  • Default: smtp.sendgrid.net

This is SendGrid's standard SMTP endpoint and rarely needs to be changed — verify with the SendGrid documentation if unsure.

sendgrid_port¤

SendGrid SMTP server port: 465 (SMTP with SSL/TLS, recommended default), 587 (SMTP with STARTTLS), or 25 (unencrypted, not recommended — often blocked by ISPs).

  • Optional
  • Environment Variable: SENDGRID_PORT
  • Default: 465

Must match sendgrid_security — port 465 pairs with SSL and port 587 with STARTTLS.

sendgrid_security¤

SMTP connection security protocol: SSL (recommended, default), STARTTLS (upgrade to TLS after initial connection), or NONE (no encryption, not recommended).

  • Optional
  • Environment Variable: SENDGRID_SECURITY
  • Default: SSL

SSL on port 465 is recommended and STARTTLS on port 587 is also secure — never use NONE in production.

sendgrid_authentication¤

Enables SMTP authentication for SendGrid connections — true or false.

  • Optional
  • Environment Variable: SENDGRID_AUTHENTICATION
  • Default: true

Must remain true: authentication is required by SendGrid and uses the subuser credentials — disabling it will cause the connection to fail.

sendgrid_api_url¤

SendGrid REST API endpoint used by the role for subuser creation and management — a valid SendGrid API hostname.

  • Optional
  • Environment Variable: SENDGRID_API_URL
  • Default: api.sendgrid.com

This is SendGrid's standard API endpoint and rarely needs to be changed. It is used during role execution only, not by MAS itself.

Debugging¤

sendgrid_debug¤

Enables display of detailed SendGrid REST API call results in Ansible logs — True or False.

  • Optional
  • Environment Variable: SENDGRID_DEBUG
  • Default: False

Warning

Use only for troubleshooting and disable it afterwards — when True, detailed API responses are logged, which may include sensitive information.

Example Playbook¤

Generate a configuration¤

- hosts: localhost
  any_errors_fatal: true
  vars:
    mas_instance_id: inst1
    mas_config_dir: /home/me/masconfig
    smtp_type: sendgrid
    sendgrid_primary_username: myusername
    sendgrid_primary_email: myemail@mydomain
    sendgrid_subuser_username: mysubusername
    sendgrid_subuser_email: mysubuser@mydomain
    sendgrid_defaultrecipientemail: myemail@mydomain
    sendgrid_defaultsendername: 'My Name'
    sendgrid_primary_apikey: xxxx
    sendgrid_ips: '["XXX.XXX.XXX.XXX"]'

  roles:
    - ibm.mas_devops.smtp

License¤

EPL-2.0