Step-by-Step: Using SMTP for sending mails

AppGini

Looking around the forum, I see that many users are having problems setting up and sending emails via SMTP. Isolated tips sometimes do NOT lead to success. Here I provide a structured step-by-step guide.

Step 1: Configure SMTP

1.1 Login as administrator

1.2 Enter Admin-Area

1.3 Open Utilities menu and go to Admin Settings

1.4 Scroll down to email settings and enter the credentials your provider has given to you

Important

  • Check SMTP option.
  • Don't play around right now.
    Just use the settings your provider has given to you for now.

1.5 Save changes


Step 2: Test SMTP in Admin Area

2.1 Open Members menu and go to View Members

2.2 Find your “admin” account and the button for sending emails at the end of the row

2.3 Enter a test-subject and test-body.



I strongly recommend putting a serial number there. This will help you in case e-mails do arrive for example hours later.

2.4 Check “Display debugging info”


This may help you later on finding and fixing the error.

2.5 Send test-message

and confirm the dialog


2.6 Be patient

2.7 Be patient

Especially if there is something wrong, it may take longer than expected.

2.8 Success or Failure

Luckily you turned on debugging and were patient. The result is displayed

2.8.2 Sending message has failed

Go back to step 1.4 and change your settings.

Tipp Don't just guess on any servernames or port numbers. Most of the time the information provided by your provider is correct. If necessary, try all possible combinations or encryption-option + available portnumbers in a structured order.

Intentionally my first attempts failed. I had to go back to step 1.4 and change encryption setting.

2.8.1 Success

Quickly check if the test email has arrived in your mailbox

Continue with step 3, if the sending has worked.

Do not cross this line, if the tests have not worked up to here.

Step 3: Test with PHP code

Before we write the mail-function we actually want, we will first run a test.

3.1 PHP code in header-extras

Follow the next 10 steps:

(1) Start your code editor and...

(2) open the file hooks/header-extras.php.

(3) Copy the following source code from here into your file:

<?php

$mail = [
    "to" => "your-mail-address@your-mailserver.tld",
    "name" => "Your name",
    "message" => "Test-message (1)",
    "subject" => "Test-subject (1)",
    "debug" => 4
];

sendmail($mail);

(4) Change the recipient email-address ("to") and (5) the recipient-name ("name") and...

(6) save the file.

(7) Switch to the browser and...

(8) reload any page of that web application.

You will see debug output directly in your page:

If this works fine, then...

(9) cut the code from header-extras.php and...

(10) save header-extras.php.

Step 4: Integrate with your PHP code

Insert the source code where you actually want to send your mails, for example in an after_update hook. Then test it, modify, test and repeat.

Tip Take one small step at a time, then test, then take the next step.

Pitfalls

  • The "to" parameter must not contain more than one recipient.
  • There is no option for multiple recipients
  • Don't try to put a comma-separated or similar.
  • There is no "cc" nor "bcc" option.
  • Be careful with single quotes and double quotes when concatenating strings in PHP.
  • Even if the sending worked, email providers may consider your email as SPAM. This can have many reasons.
  • Make sure that the sender email address matches the domain name.

Tipps

  • When concatenating strings start simple and test every step. If successfull, change the string and test again.
  • For multiple recipients create an array of strings and use foreach for sending.
  • Consider sending to an shared inbox which can be read by multiple users.
  • Consider using a modern code-editor with syntax highlighting. Such an editor will automatically show syntax errors and give hints how to solve them.
  • If step 2 was not successful, you do not need to continue with steps 3 or 4. It cannot work if the foundation is not there.
  • If sending worked, but still no mail arrives, check your SPAM folder.
  • Check the SMTP settings character by character to exclude spelling mistakes.

I hope this guide was helpful. Feel free to give me feedback by email.

Do you like it?