This page documents how email sending is configured in the StudentHub backend, including the configuration of the mailer component, the definition and use of "From" addresses, and the code paths for verification and other transactional emails. It is intended to give backend developers a clear map of where to change SMTP providers, which addresses are used, and what parts of the app are affected by such changes.

Mailer Component Configuration#

Configuration Files#

The mailer component is not configured in common/config/main.php. Instead, it is defined in environment-specific files:

• Development: environments/dev/common/config/main-local.php
• Production: environments/prod/common/config/main-local.php

Development (environments/dev/common/config/main-local.php)#

In development, the mailer component is configured as follows:

'mailer' => [
    'class' => \yii\symfonymailer\Mailer::class,
    'viewPath' => '@common/mail',
    'useFileTransport' => true,
],

• useFileTransport is set to true, so emails are not sent but saved as files in the runtime directory. No SMTP transport is active by default. To enable real email sending in development, set useFileTransport to false and add a transport configuration block source.

Production (environments/prod/common/config/main-local.php)#

In production, the mailer component is configured with an active SMTP transport:

'mailer' => [
    'class' => \yii\symfonymailer\Mailer::class,
    'viewPath' => '@common/mail',
    'transport' => [
        'scheme' => 'smtp',
        'host' => 'email-smtp.eu-west-1.amazonaws.com',
        'username' => '<AWS_SES_SMTP_USERNAME>',
        'password' => '<AWS_SES_SMTP_PASSWORD>',
        'port' => 587,
        // 'dsn' => 'smtp://<username>:<password>@email-smtp.eu-west-1.amazonaws.com:587',
    ],
],

• Active SMTP Provider: Amazon SES (Simple Email Service), region eu-west-1, port 587, scheme smtp.
• Credentials: Set in the config file (do not commit secrets to version control).
• Class: Uses yii\symfonymailer\Mailer source.

Commented-Out Alternative Providers#

The production config file contains commented-out blocks for alternative SMTP providers, including:

• ElasticEmail: smtp.elasticemail.com, port 2525, TLS
• Mailgun: smtp.eu.mailgun.org, port 587, TLS
• SendGrid: smtp.sendgrid.net, port 587, TLS

These blocks include example credentials and can be activated by uncommenting and updating as needed source.

"From" Addresses and Display Names#

Definition#

The following parameters are defined in common/config/params.php:

'appName' => 'StudentHub',
'supportEmail' => 'contact@studenthub.co',
'adminEmail' => 'khalid@studenthub.co',

• supportEmail: Used as the "From" address for verification and most transactional emails.
• adminEmail: Used for admin-related notifications.
• appName: Used as the display name for outgoing emails.

There are no environment-specific overrides for these values by default (i.e., no params-local.php files override these keys) source.

Actual "From" Address and Display Name Used#

• Development: contact@studenthub.co (display name: StudentHub)
• Production: contact@studenthub.co (display name: StudentHub)

Unless a params-local.php override is introduced, both environments use the same values.

Verification Email Sending in Code#

Candidate::sendVerificationEmail()#

Located in common/models/Candidate.php, this method is responsible for sending verification emails. The process is as follows:

1. Generates an authentication key for the candidate.
2. Updates the candidate's last email timestamp.
3. Determines the recipient email: uses candidate_new_email if set, otherwise candidate_email.
4. Logs the email in the MailLog model.
5. Composes the email using both HTML (candidate/verify-email-html) and text (candidate/verify-email-text) templates.
6. Sets the "From" address to Yii::$app->params['supportEmail'] and the display name to Yii::$app->params['appName'].
7. Sets the subject to "Please confirm your email address".
8. Adds an ElasticEmail poolName header if Yii::$app->params['elasticMailIpPool'] is set.
9. Sends the email using Yii::$app->mailer.

Example code snippet:

$mailer = Yii::$app->mailer->compose([
    'html' => 'candidate/verify-email-html',
    'text' => 'candidate/verify-email-text',
], [
    'candidate' => $this
])
->setFrom([Yii::$app->params['supportEmail'] => Yii::$app->params['appName']])
->setTo($email)
->setSubject('Please confirm your email address');

if (Yii::$app->params['elasticMailIpPool']) {
    $mailer->setHeader("poolName", Yii::$app->params['elasticMailIpPool']);
}

return $mailer->send();

source

Controller Actions and API Endpoints#

The following controller actions call Candidate::sendVerificationEmail():

• actionSignup in candidate/modules/v1/controllers/AuthController.php

  • API endpoint: POST /candidate/v1/auth/signup (or /candidate/v1/auth/register depending on routing)
  • Called when a candidate registers via the public signup API.

• actionResendVerificationEmail in candidate/modules/v1/controllers/AuthController.php

  • API endpoint: POST /candidate/v1/auth/resend-verification-email
  • Called to resend the verification email if the candidate's email is not yet verified.

• actionUpdateEmail in candidate/modules/v1/controllers/AuthController.php

  • API endpoint: POST /candidate/v1/auth/update-email
  • Called when a candidate updates their email address, triggering a new verification email.

These actions enforce rate limiting and candidate status checks before sending source.

Other Transactional Email Flows Using the Same Mailer#

All transactional emails use the same mailer configuration and "From" address as verification emails. These include:

• Password reset: Candidate::sendPasswordResetEmail() (template: candidate/password-reset-html, subject: "Reset your StudentHub password"). Called by actionRequestResetPassword in AuthController (POST /candidate/v1/auth/request-reset-password).
• Password updated notification: Candidate::sendPasswordUpdatedEmail() (template: candidate/password-updated-html, subject: "Your password reset was a success").
• OTP for two-step verification: Candidate::sendOTPMail() (template: candidate/candidate-otp, subject: "OTP for 2 step verification").
• Notifications:
  • commitmentWarningEmail() (template: candidate/commitment-warning)
  • kuwaitiNationalityEmail() (template: candidate/kuwaiti-mom)
  • notifyCivilIDExpiring() (template: candidate/civil-id-expiring, uses finance_transfer as From address)
  • notifyMissingBankInfo() (template: candidate/request-bank-information, uses finance_transfer as From address)
  • birthdayAlert() (template: birthday)

All these methods are implemented in common/models/Candidate.php and use Yii::$app->mailer with the From address set to supportEmail (or finance_transfer for some finance-related notifications) and the display name set to appName source.

Changing the SMTP Provider or "From" Address#

• To change the SMTP provider:
  Edit the transport section of the mailer component in environments/prod/common/config/main-local.php. Update the host, port, scheme, and credentials as needed. To switch to an alternative provider, uncomment and update the relevant block (ElasticEmail, Mailgun, SendGrid) source.

• To change the "From" address or display name:
  Edit supportEmail and appName in common/config/params.php. If you need environment-specific overrides, create or edit params-local.php in the relevant environment directory.

• Impact of changes:
  All transactional email flows (verification, password reset, OTP, notifications) use the same mailer and From address configuration. Changing the SMTP provider or From address will affect all these flows.

• Testing in development:
  By default, the dev environment does not send real emails. To test real email sending, set useFileTransport to false and configure a transport in environments/dev/common/config/main-local.php.

Summary Table#

Key File Paths#

• common/config/params.php — Defines supportEmail, adminEmail, appName.
• environments/dev/common/config/main-local.php — Dev mailer config.
• environments/prod/common/config/main-local.php — Prod mailer config, SMTP settings, alternative providers.
• common/models/Candidate.php — All transactional email methods.
• candidate/modules/v1/controllers/AuthController.php — API endpoints triggering verification and password reset emails.

For further changes, always review both the environment-specific mailer config and the shared params file to ensure consistency across all transactional email flows.