Connect Two Systems (Integration)

tutorial

by Christian Clausen

on Jun 30, 2025 (created Nov 14, 2024) • 4 min

In this tutorial we're going to use Merrymake to connect two 3rd-party APIs; to send ourselves an email with a random joke every day.

Prerequisites

First, open Git Bash. If you don't have Git Bash, get it from https://git-scm.com/ .

We also need to make sure we have NodeJS installed. We can test this by running this command in Git Bash:

$ npm --version

It should give something like 10.2.3. If not get it from https://nodejs.org/ The final tool we need is the Merrymake CLI, which uses Git and NodeJS. Install the CLI with the command:

$ npm install --global @merrymake/cli

Start Using Merrymake

With the CLI installed, we are ready to start using Merrymake. The first command we should run on every device we want to use Merrymake on is:

$ mm start

The mm tool now guides us through the initial process. Select:

  1. setup new key specifically for Merrymake
  2. Input your email address
  3. create new organization
  4. Name your organization or press enter to accept the suggested name
  5. initialize with a basic template
  6. typescript
  7. deploy the service immediately
  8. post an event to the rapids
  9. Input your name (or anything)
  10. Input admin key
  11. Press enter to accept the suggested duration (14 days)

We should now see Hello, XXXX!, this means our service is running in the cloud. If you don't see this please reach out on our Discord to get assistance.

Send Emails

We are ready to start sending emails. We navigate into the repository we just created with the command:

$ cd [organization name]/back-end/service-1

We'll use Mailgun as the email provider, so head over there and sign up for a free account. Remember to verify your email. Then, we need to create an API key and copy it. We put this API key in a secret environment variable with the command:

$ mm envvar
  1. Input MAILGUN
  2. the value is secret
  3. Insert the API key
  4. accessible in both prod and init run

We also need to grab our Mailgun trial email domain.

  1. Navigate to Send › Sending › Overview.
  2. Add your email to the "Authorized Recipients" on the right.
  3. Verify your email again.
  4. Copy your trial email domain
  5. Put that in another secret envvar:
    $ mm envvar new EMAIL_DOMAIN secret
    Insert the trial domain xxxxxxxxxxx.mailgun.org, accessible in both prod and init run.

To work with Mailgun we need to install an npm package for it:

$ npm install mailgun.js

Open the file index.ts and replace its content with this:

back-end/service-1/index.ts
import { merrymakeService } from "@merrymake/service";
import Mailgun from "mailgun.js";

async function handleSendEmail(payloadBuffer: Buffer) {
  const joke = payloadBuffer.toString();
  const mailgun = new Mailgun(FormData);
  const mg = mailgun.client({
    username: "api",
    key: process.env.MAILGUN!,
  });
  mg.messages.create(process.env.EMAIL_DOMAIN!, {
    from: `Merrymake <merrymake@${process.env.EMAIL_DOMAIN!}>`,
    to: ["YOUR@EMAIL.com"],
    subject: "Daily Joke",
    text: joke,
  });
}

merrymakeService({
  handleSendEmail,
});

Notice: Remember to change YOUR@EMAIL.com

Since we've changed the function name we also need to update the hooks in merrymake.json, so replace its content with this:

back-end/service-1/merrymake.json
{
  "hooks": {
    "main/send-email": "handleSendEmail"
  }
}

We can test to verify that our code works by deploying it

$ mm deploy

And triggering it with

$ mm rapids post send-email text "This is a test" _

It should say Queued job. and within 15 minutes an email should arrive in your inbox (or spam folder).

Get a Random Joke

To fetch a random joke we install a package for making HTTP requests:

$ npm install axios

We use this library to call another 3rd-party API called iCanHazDadJoke . Open the file index.ts and replace it's content with this:

back-end/service-1/index.ts
import {
  merrymakeService
  postToRapids,
} from "@merrymake/service";
import Mailgun from "mailgun.js";
import axios from "axios";

async function runDaily(payloadBuffer: Buffer) {
  const resp = await axios.get("https://icanhazdadjoke.com/", {
    headers: { Accept: "text/plain" },
  });
  postToRapids("send-email", resp.data);
}

async function handleSendEmail(payloadBuffer: Buffer) {
  const joke = payloadBuffer.toString();
  const mailgun = new Mailgun(FormData);
  const mg = mailgun.client({
    username: "api",
    key: process.env.MAILGUN!,
  });
  mg.messages.create(process.env.EMAIL_DOMAIN!, {
    from: `Merrymake <merrymake@${process.env.EMAIL_DOMAIN!}>`,
    to: ["YOUR@EMAIL.com"],
    subject: "Daily Joke",
    text: joke,
  });
}

merrymakeService({
  runDaily,
  handleSendEmail,
});

Since we've changed the function name we also need to change the hook:

back-end/service-1/merrymake.json
{
  "hooks": {
    "main/send-email": "handleSendEmail",
    "main/daily": "runDaily"
  }
}

Now to deploy the service we simply run:

$ mm deploy

The Merrymake platform automatically builds, packages, and deploys the service, and then hooks it up for traffic.

Run on a Schedule

The only thing left is to trigger the service automatically once every day. Merrymake supports recurring jobs out of the box. We do declare our recurring events in the event-configuration folder

$ cd ../../event-configuration

Here we can replace the content of cron.json

event-configuration/cron.json
{
  "daily": { "expression": "0 0 0 ? * * *" }
}

Save the file and deploy the event-configuration:

$ mm deploy

Conclusion

Using the CLI we have:

We have seen how to implement and deploy a serverless back end with two co-deployed services that communicate.

These are the basic steps to connect two 3rd-party systems with Merrymake.

Christian Clausen
Nov 14, 2024