Sending emails with Hyperlambda and Magic
Most web applications needs to send emails at some point. These can be simple “Thank you for registering” emails, to “Reset your password” template emails, where you need to braid in the user’s full name, his or her email address, and additional data to create a customised email from some template of some sort. However, before you can send emails at all, you’ll have to configure Magic such that it has access to some SMTP server of some sort. Below you can see the configuration settings related to this.
{
"magic":{
"smtp":{
"host":"smtp.gmail.com",
"port":465,
"secure":true,
"username":"username@gmail.com",
"password":"gmail-password",
"from": {
"name":"John Doe",
"address":"john@doe.com"
}
}
}
}
Notice, keep the rest of your settings as is and make sure you only add the above smtp
section to your root
magic
configuration object. The exact values of the above fields varies according to your particular SMTP server’s
values of course, but if you want to use GMail as your SMTP server, all you need to do is to open up your GMail account
for “Insecure apps” and change the above username/password to your GMail account’s username and password. Below is a
screenshot of how you can edit your configuration settings using the “Config” menu item in Magic.
At this point you can try your SMTP configuration be executing the following in Magic’s “Eval” menu item.
mail.smtp.send
message
to
Your Name Here:your-email@address-here.com
from
Whatever From Name Here:whatever-email@address-here.com
subject:Test email from Magic
entity:text/plain
content:This is a test!
Below is a screenshot of how this looks like for me.
Internals
The above invocation to [mail.smtp.send] is given one [message] argument. Notice, you can supply as many [message] arguments as you wish in a single invocation to the slot. This has some advantages since each invocation to [mail.smtp.send] has to negotiate a new connection to your SMTP server, which carries some overhead. Also notice the [entity] argument above. This declares a MIME entity, which is extremely flexible in Magic, allowing you to reference files directly from disc as attachments, create multipart messages, etc. For a slightly more complex example consider the following Hyperlambda.
mail.smtp.send
message
to
Your Name Here:your-email@address-here.com
from
Whatever From Name Here:whatever-email@address-here.com
subject:Test email from Magic
entity:multipart/mixed
entity:text/plain
content:This is a test!
entity:text/plain
filename:/README.md
If you execute the above Hyperlambda, you will notice that it creates an attachment. The reasons for that
is because you’ve got a [filename] entity child argument to your multipart/mixed
part. This results
in that the MIME parts of Magic automatically adds it as an attachment using the Content-Disposition
header,
and adds the correct relative filename. You can use any feature from MIME as illustrated above in Magic and
Hyperlambda, to construct emails any ways you see fit. Below is a screenshot illustrating how it looks like
as I received the above email in my personal inbox.
Template emails
Typically when creating a web app needing to send emails, you’ve got a “template” of some sort, which you use as your foundation, for then to use this template, apply some string replacements to add personalised data, before you send your email. Magic has strong support for sending such emails out of the box. More specifically Hyperlambda contains a dynamic slot named [magic.emails.send] that allows you to create such “braided” emails. However, this slot assumes you’ve already got a “template” that you want to base your email upon. Hence, for the sake of testing the slot, first make sure you create a file inside your “/etc/” folder named “test-email.html” and add the following content to it. You can use Hyper IDE to create this file.
Content of your “test-email.html” file
<p>Thank you {{name}} for wanting to read my email. This makes me so jazzed!</p>
<p>Feel free to <a href=”https://docs.aista.com”>check out the docs</a> for Aista Magic Cloud ^_^</p>
Then execute the following Hyperlambda in your “Eval” menu item.
signal:magic.emails.send
subject:Template email from Hyperlambda
email:your-email@address.com
name:Your Name Here
mime-type:text/html
template-file:/etc/test-email.html
substitutes
name:Your Name Here
attachments
entity:text/plain
filename:/README.md
entity:text/plain
filename:/exceptions.hl
Below is how it looks like if I send myself an email after having substituted the above [email] and [name] argument(s).
As you can see above the {{name}} part from the template was automatically substituted with my name. You can provide as many substitutions as you wish. Notice, how the attachments are automatically transformed into attachments in the resulting email. If you want to further study the email capabilities of Magic and Hyperlambda you can check out the documentation for magic.lambda.mail and magic.lambda.mime.
- Continue with Allow users to register in your backend