# Emails

I've built 5 SaaS in the last 2 years, and I know how email is crucial to engage with your customers, still in 2024.

**Shipped** comes with support for two popular products, [MailChimp](https://mailchimp.com/) and [Loops](https://loops.so/).

Both allow you to:

* Collect user emails
* Send product update emails to the subscribers
* Configure an email drip
* Send transactional emails from your product

## MailChimp setup

Configure these environment variables `MAILCHIMP_AUDIENCE_LIST_ID`, `MAILCHIMP_API_KEY`, and `MAILCHIMP_SERVER_PREFIX`.

### Find your Audience ID

You need it to add the users to your email list.

Log in to your [MailChimp](https://mailchimp.com/) account and then:

1. Click **Audience**
2. Click **All contacts**
3. If you have more than one audience, click the **Current audience** drop-down and choose the one you want to work with.
4. Click the **Settings** drop-down and choose **Audience name and defaults**.
5. In the **Audience ID** section, you’ll see a string of letters and numbers. This is your audience ID.

Save the value into `MAILCHIMP_AUDIENCE_LIST_ID` in the .env file

### Create your API Key

Needed to send transactional emails.

1. Navigate to the [**API Keys**](https://us1.admin.mailchimp.com/account/api/) section of your account.
2. Click **Create New Key**.
3. Name your key. Be descriptive, so you know what app uses that key. Keep in mind that you’ll see only this name and the first 4 key digits on your list of API keys.
4. Click **Generate Key**.
5. Once we generate your key, click **Copy Key to Clipboard**. Save your key someplace secure–you won’t be able to see or copy it again. If you lose this key, you’ll need to generate a new key and update any integration that uses it.
6. Click **Done**.

Save the value into `MAILCHIMP_API_KEY` in the .env file

### Configure server prefix

To find the value for the `server` log into your Mailchimp account and look at the URL in your browser. You’ll see something like `https://us19.admin.mailchimp.com/` \
The `us19` part is the server prefix. Note that your specific value may be different.

Save the value into `MAILCHIMP_SERVER_PREFIX` in the .env file

### Add a new email contact at sign-up

Open the file `src/config/auth.ts` and uncomment `addMailChimpListMember` in the `signIn` event handler

{% code title="src/config/auth.ts" %}

```typescript
events: {
  async signIn(event) {
    if (event.isNewUser && event.user.email) 
      await addMailChimpListMember({
        email: event.user.email,
        firstName: event.user.name || "",
        lastName: "",
        tags: ["new-user"],
      });

    }
  },
},
```

{% endcode %}

{% hint style="info" %}
Learn more about the MailChimp Marketing API on the [documentation](https://mailchimp.com/developer/marketing/api/)
{% endhint %}

### Send transactional email

```typescript
import { sendTransactionalEmail } from "@/libs/mailchimp";

await sendTransactionalEmail({
    to: ["john@doe.com", "jane@doe.com"],
    subject: "You reached the limits",
    text: "Upgrade to get more requests",
    html: "<p>Upgrade to get more</p>"
})
```

### Send transactional email with template

Define and store your template in MailChimp.

```typescript
import { sendTransactionalEmailWithTemplate } from "@/libs/mailchimp";

await sendTransactionalEmailWithTemplate({
    to: ["john@doe.com", "jane@doe.com"],
    subjplateName: "my template",
    mergeTags: [{ 
        name: "merge1",
        content: "merge1 content",
    }]
})
```

{% hint style="info" %}
Learn more about the MailChimp Transactional API on the [documentation](https://mailchimp.com/developer/transactional/api/)
{% endhint %}

## Loops setup

To set up Loops you need to create an API Key.

{% embed url="<https://www.youtube.com/watch?v=SwedBn58NIM>" %}
How to use Loops for Magic Link with NextAuth
{% endembed %}

### Create API Key

1. Log in to [Loops](https://loops.so/)
2. Go to **Settings**
3. Click on **API**
4. Click on **Generate key**
5. Copy the key and paste it to `.env` as the value for `LOOPS_API_KEY`

### Add a new contact at sign-up

Open the file `src/config/auth.ts` and uncomment `createLoopsContact` in the `signIn` event handler

{% code title="src/config/auth.ts" %}

```typescript
events: {
  async signIn(event) {
    if (event.isNewUser && event.user.email) {
      await createLoopsContact({
        email: event.user.email,
        firstName: event.user.name || "",
        lastName: "",
        userGroup: "new-user",
      });

    }
  },
},
```

{% endcode %}

### Send a transactional email

Go to Loops and create a new Transactional. Copy the transactional id.

```typescript
import { sendTransactionalEmail } from "@/libs/loops";

await sendTransactionalEmail({
    "clfq6dinn000yl70fgwwyp82l", // <-- transactional id
    "john@doe.com", // <-- to email
    {
        loginUrl: "https://myapp.com/login/" // <-- dynamic content
    }
})
```

{% hint style="info" %}
Learn more about the Loops API in the [documentatio](https://loops.so/docs/sdks/javascript)[n](https://loops.so/docs/sdks/javascript)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.shipped.club/features/emails.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.