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.

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

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

$ npm install --save mailgun-js

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");

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);

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']

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. ! 😍`
};

Finally it’s time to send the email.

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

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

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

$ cd ..
$ tar -zcvf code.tar.gz cloud-functions-demo

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

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.

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.

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)

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

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

Your welcome email should be in your inbox now! 😀

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

• You can find the complete code sample and lots of other demos in our Cloud Functions Demo Repo.
• Check out Appwrite's Github Repo.
• Our Discord Server is the place to be if you ever get stuck.
• You can find all our Documentation here.