Error handling Email error | Sharing personal experience

[JeffreyArts]

Some context

As a newby with Payload, I'm on a quest to set-up the full authentication for website users. Part of this is being able to send e-mails to the users, which this discussion will be about. I'm sharing here my experience and expect this to be read as is. Goal of this is to provide the maintainers of the documentation and or codebase to make adjustments where they see necessary.

---

Updating email configuration

Understanding that I need to add an e-mail service, I went too the documentation and found this page:. Reading through this document and having a Mailgun account, I decided to implement to go for the second (and recommended) implementation option; Set the transportOptions and Payload will do the set up for you.. So I went to my server.ts file and added the following object to the payload.init options;

    email: {
      fromName: "Admin",
      fromAddress: "[email protected]", // Replaced this with my actual e-mailaddress
      transportOptions: {
        host: process.env.SMTP_HOST,
        auth: {
          user: process.env.SMTP_USERNAME,
          pass: process.env.SMTP_PASSWORD,
        },
        port: Number(process.env.SMTP_HOST),
        secure: Number(process.env.SMTP_PORT) === 465, // true for port 465, false (the default) for 587 and others
        requireTLS: true,
      },
    },

Finding SMPT configuration settings in Mailgun where quite clear in their app, so I configured the SMTP_HOST, SMTP_USERNAME, SMTP_PASSWORD & SMTP_PORT in my .env file and received the following error after an (automatic) server restart: ERROR (payload): There is an error with the email configuration you have provided. Error: connect ECONNREFUSED ::1:587. I felt a bit in the dark at first, but that was totally on me. Cause the error message contains ::1:587 indicating that there is something wrong with the hostname. Having taken a look at my .env file, I did notice that I made a mistake and renamed SMPT_HOSTNAME to SMTP_HOST. Perfectly fine experience, error message was clear, I just misread it.

Next thing to do is to send a test message, in the same documentation page I read that I can sent a message with the payload.sendEmail method. So in the onInit function, I've added the following code, a modified version from the one that the documentation suggest

      var message = {
        to: "[email protected]", // Replaced this with my actual e-mailaddress
        subject: "Message title",
        text: "Plaintext version of the message",
        html: "<p>HTML version of the message</p>",
      };
      
      payload.sendEmail(message).then(data => {
        console.log("Message sent")
        console.log(data)
      }).catch(err => {
        console.log("Message not set")
        console.error(err)
      })

This did not send a test e-mail to the e-mailaddres I had provided, but the data object gave me a hint on why I probably did not receive this message. It was lacking the "from" property. Going back to the Nodemailer documentation that the Payload documentation provided, I tried to add a 'from' property and that resolved the problem. Maybe there is a good reason why this is required or perhaps it is a bug, but either way, I was expecting that the from address would be pre-filled with the 'email.fromAddress' that I just configured. Nonetheless it is not a big deal, and was easy to resolve.

Conclusion

While it is unclear to me why the 'fromAddress' is required to define in the email configuration when it is not being used as the default value in a 'sendEmail' method, is a bit confusing to me. But overall the developer experience to implement an e-mail server was very positive. At one point I was doing something that my Mailgun (dev)account did not allow and I was getting that error message clearly in my console. While that error handling is done by nodemailer and payload is not responsible for how they handle their error messages, for me as an end-user I enjoyed that nonetheless.

Also noticing that when stuff ain't working, because I am misreading the error messages creates trust in the architecture of Payload. Since clearly I am the one to blame. The construct of the documentation & codebase are good enough to resolve these issues myself. That makes me happy :)