Sending a Custom Welcome Email Using Appwrite Functions and Mailgun
Tags: serverless, tutorial, node, javascript
Published: 2021-03-15 16:22:42

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](https://appwrite.io/docs/webhooks).

In this example, we will demonstrate how we can send welcome emails to newly registered users using [Mailgun’s Email API](https://www.mailgun.com/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.

<p align="center">
    <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7q33tidf62jpkukp02wg.png" alt="Create Function Dialog" width="600"  />
</p>

## 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.

```sh
$ 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
```sh
$ npm install --save mailgun-js
```

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

```js
// Import the mailgun sdk
const mailgun = require("mailgun-js");
```

We then setup the Mailgun sdk

```js
// 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](https://appwrite.io/docs/functions). 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.

```js
// 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.

```js
// 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.
```js
// 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.

```sh
.
├── index.js
├── node_modules/
├── package-lock.json
└── package.json
```
We package the function by creating a `tarfile` out of our folder. 

```sh
$ 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:
```sh
$ 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.

<p align="center">
    <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4ey978ygvfaljbu5kcio.png" alt="Deploy Tag" width="600"  />
</p>

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. 

<p align="center">
    <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uwuemysknqttw8imxkv3.png" alt="Set Trigger" width="600"  />
</p>

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)

<p align="center">
    <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ep7b8kreuno4u0uhndi2.png" alt="Create User Dialog" width="600"  />
</p>


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

<p align="center">
    <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9vtbtwvtz35iiteiyutk.png" alt="Function Execution Logs" width="600"  />
</p>

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

<p align="center">
    <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pcfcngupzmx5fs98vt50.png" alt="Email API Response" width="600"  />
</p>

Your welcome email should be in your inbox now! 😀

<p align="center">
    <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pijzrjqnt0zdd8seeq1d.jpg" alt="Email from Cloud Function" height="300"  />
</p>


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](https://github.com/appwrite/demos-for-functions/tree/master/nodejs/welcome-email).  
* Check out [Appwrite's](https://github.com/appwrite/appwrite) Github Repo.
* [Our Discord Server](https://appwrite.io/discord) is the place to be if you ever get stuck.
* You can find all our Documentation [here](https://appwrite.io/docs).