DEV Community

Cover image for Sending a Custom Welcome Email Using Appwrite Functions and Mailgun
Christy Jacob for Appwrite

Posted on

Sending a Custom Welcome Email Using Appwrite Functions and Mailgun

In this tutorial, we will cover how we can leverage Appwrite’s Cloud Functions feature to execute certain tasks when certain events take place in the server. You can find a complete list of available system events here.

In this example, we will demonstrate how we can send welcome emails to newly registered users using Mailgun’s Email API. A similar concept applies to other API providers like Twillio’s Sendgrid or MailChimp.

Create your Cloud Function

The first step is to create a MailGun account and obtain the API Key for their Email API. Now let's create the Cloud Function in the Appwrite Console. Head over to the Functions section of your console and select Add Function. You can give your function a funky new name and select the preferred environment. We will be using Node.js for this example.

Create Function Dialog

Let's write some code

The next step is to write the code that will be executed and upload it to the Appwrite Server. Create a directory to hold your Cloud Function and create your index.js file.

$ mkdir cloud-functions-demo 
$ cd cloud-functions-demo
$ npm init
$ touch index.js
Enter fullscreen mode Exit fullscreen mode

We will be using just one dependency for this example so let's install it using

$ npm install --save mailgun-js
Enter fullscreen mode Exit fullscreen mode

Great. It’s time to start editing the index.js file. We start by importing the relevant libraries.

// Import the mailgun sdk
const mailgun = require("mailgun-js");
Enter fullscreen mode Exit fullscreen mode

We then setup the Mailgun sdk

// Create a config object and initialise the mailgun SDK
const emailConfig = {
    apiKey: process.env.MAILGUN_API_KEY,
    domain: process.env.MAILGUN_DOMAIN
};
const mg = mailgun(emailConfig);
Enter fullscreen mode Exit fullscreen mode

When a function is triggered by an event, we can obtain a lot of metadata about the event from some special environment variables that are set by Appwrite. A complete list is available here. In our case, we need the name and email ID of the newly registered user. Appwrite conveniently exposes this information as an environment variable named: APPWRITE_FUNCTION_EVENT_PAYLOAD. Let’s parse this JSON string to retrieve the name and email.

// Get the name and email of the newly created user from Appwrite's environment variable
const payload = JSON.parse(process.env.APPWRITE_FUNCTION_EVENT_PAYLOAD)
const name = payload['name']
const email = payload['email']
Enter fullscreen mode Exit fullscreen mode

Now it’s time to add your recipients, sender, subject and body of the email.

// Create your email 
const data = {
    from: 'Welcome to Appwrite <welcome@appwrite.io>',
    to: email,
    subject: `Welcome on board ${name}!`,
    text: `Hi ${name}\nGreat to have you with us. ! 😍`
};

Enter fullscreen mode Exit fullscreen mode

Finally it’s time to send the email.

// Send the email! ❤️
mg.messages().send(data, function (error, body) {
    console.log(body);
});
Enter fullscreen mode Exit fullscreen mode

Packaging the Cloud Function

Before we can package our cloud function, we need to ensure that our directory has the following structure.

.
├── index.js
├── node_modules/
├── package-lock.json
└── package.json
Enter fullscreen mode Exit fullscreen mode

We package the function by creating a tarfile out of our folder.

$ cd ..
$ tar -zcvf code.tar.gz cloud-functions-demo
Enter fullscreen mode Exit fullscreen mode

We can now upload this tar file to our function’s dashboard by selecting the Deploy Tag option. Our entry point command, in this case, would be:

$ node index.js
Enter fullscreen mode Exit fullscreen mode

Note: You can also automate the code upload process using the Appwrite server SDK latest version and your CI server. In future versions, Appwrite will also support this process using a dedicated CLI tool, directly from your terminal.

Deploy Tag

Once created, we need to define a trigger for the function. In our case, we wish to trigger it whenever a new user is created. So we would be interested in the users.create event. The trigger can be enabled under the Settings tab of the function.

Set Trigger

Once the triggers are enabled, it’s time for our final step, Function Variables.

Appwrite allows you to securely store secret keys using Appwrite Function Variables which will be available as environment variables to your program. The best part is that these keys are encrypted and stored securely on Appwrite’s internal DB. In this example, we have used two environment variables namely MAILGUN_API_KEY (Mailgun API Key) and MAILGUN_DOMAIN (Mailgun Domain) so let’s add them to the Function Variables in your function Settings. Don’t forget to click the Update button once you’re happy with your settings.

Great! We’re done with all the setup. All that’s left now is to test the Cloud Function.

Testing

Now it’s time to test your shiny new Cloud Function! Head over to the Users section of Appwrite and create a new user by clicking on the ‘+’ button at the bottom right.
If you’re using a sandbox Mailgun account, ensure that the email ID of this user is the same as the whitelisted ones on your dashboard, else this won’t work. (You can even create a user using your Appwrite SDK but the UI is much easier for this demo)

Create User Dialog

Your Cloud Function would now have been triggered. You can check it out by heading over to Functions > Your Function Name > Logs

Function Execution Logs

Once the execution is complete, you can check the response from the API.

Email API Response

Your welcome email should be in your inbox now! 😀

Email from Cloud Function

And in a few simple steps, we successfully deployed our first Cloud Function. The possibilities with Cloud Functions are endless! Stay tuned for more Cloud Function ideas from the Appwrite Team.

Learn More

Top comments (2)

Collapse
 
kohsheen1234 profile image
Kohsheen Tiku

Very helpful!

Collapse
 
bonglv profile image
Ly Van Bong

Can you give more specific instructions? I think the title of the article is so good, but you guys are a little bit, I don't understand it