Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/foxy/foxy-node-subscription-alert

Sends email alerts about subscription a number of days before or after the next transaction date.
https://github.com/foxy/foxy-node-subscription-alert

Last synced: 9 months ago
JSON representation

Sends email alerts about subscription a number of days before or after the next transaction date.

Awesome Lists containing this project

README 

          
# Foxy Subscription Alerts



Allows automatically sending messages for subscribers at specific configurable dates relative to the subscriptions `nextdate`.



## Usage



### Configuring your Foxy credentials



Edit the `config.js` folder in order to set up your credentials.



There are comments within the file explaining each field that must be filled.



In summary, you need to set up a refresToken, a clientSecret and a clientId.

You can find your credentials in the Foxy.io admin page:



1. Go to https://foxy.io and log in.

1. Under "ACCOUNT", click "integrations.

1. Under "Current integrations", click "Get token"

1. Provide a project name and a project description. These fields are useful for you to remember what are these tokens used for.

1. Copy the resulting credentials and paste in somewhere safe. 



In `config.js` look for the fields with corresponding names. They sould be found in line 30. 

Add your credentials to the respective key.



### Configuring your email templates

Sending alert emails can be as easy as creating a folder and some files.

All you need to do is to create a folder with the messages you want to send and within this folder create your email template.



Here is the simples example:



    - alerts/

        within-05/

            body.txt

            body.html



With this file structure in place, emails will be sent to users 5 days before their next subscription date. Also, the

messages will be sent in HTML (using the contents of the `.html` file) with a text fallback (with the contents of

the `.txt` file) for those users that for whatever reason cannot load the HTML message.



## Creating your email alerts



Each email alert is a folder within the `emails` folder.

Simply create these folders to create new email alerts. 



### Sensible defaults



There are some sensible defaults already put in place.

You can use them as they are or use them as inspiration to create your own email templates.



#### Naming your subscription alert folder

The way you name your folder will determine how it will be sent.



- **within** Name your folders `within-NUMBER` to send an alert mail about subscriptions with next_transaction_date withing NUMBER days.

- **past** Name your folders `past-NUMBER` to send an alert mail about subscriptions with next_transaction_date that occurred in NUMBER days in the past.



You can also restrict sending alerts only to `active` or `inactive` subscriptions. Prepend your folder with `active-` or `inactive-` to achieve this.



Here are some examples:



- `within-5`: sends alerts about subscriptions that will be renewed in 5 days.

- `past-12` : sends alerts about subscriptions expired 12 days ago.

- `inactive-past-2`: sends alerts about inactive subscriptions that expired 2 days ago.



#### Creating your files



You need to create at least one file in each folder, called `body.txt`, `body.html` or `body.mjml`.

The contents of this file will be the contents of your email.



You can also create a file called `subject.txt` to customize the subject of the message.



## Testing your emails



By default, Foxy Subscription Alert comes with the `testing.enabled` set to `true`. You can set it to false in the `config.js` file.



While it is set to true, instead of sending emails to your users, it will send emails to a test account.



### Where do I see the test emails?



You can either set up an email account to receive the test emails (or use your own), or you can use an Ethereal mail that is automatically created to allow you to easily view your test emails.



#### Using Ethereal mail

In the `config.js` file there is an option called `autoGenerateTestEmail`. If it is set to true the application will set a testing account for you automatically in Ethereal Mail and display the login url, name and password for you to view your test emails.



It will display a helpful message with the link to access your test account, a user and a password. After logging in to your test account, click on "Messages" in the top menu in order to read the test emails.



**Notice:** when using Ethereal mail your SMTP configuration is not used. This means that the fact that these tests work **do not mean that your SMTP configuration is correct**.

Please, double check your SMTP configuration if you are not getting your emails.



#### Using your own test email address



In the `config.js` file there is an option called `autoGenerateTestEmail`. Set it to `false` and set `customTestEmail` to the email where you would like to receive the tests.



### Testing with testing disabled



If you need to send a test email, but does not wish to (or can't) change the config file, you can always test new emails by simply using the `test` command line argument:



```bash

#send real emails

node index.js

#send test emails

node index.js test

```

## Composing emails



You can compose your emails in plain text, HTML or MJML. If you don't provide a plain text version, one will be automatically created for you.



Pro-tip: consider using MJML to send responsive emails that will look nice everywhere.



Note: all emails are related to a single subscription.



### Using variables



You can use the [Twig templating language](https://twig.symfony.com/doc/3.x/templates.html) to compose your emails.



If you are not familiar with Twig, this might help:



- Variable substitution: use double curly braces to use a variable: `Hi {{ customer.first_name }}, please confirm your email is {{ customer.email }}`.

- Loop: use a "for loop" to display a list of things: `here are the products in your subscription: {% for item in items %} {{ item.name }} {% endfor %}`.



#### Available variables



Here are the variables you will have available when writing your email templates:



| Variable            | Description                                                   |

| ------------------- | ------------------------------------------------------------- |

| customer            | Information about the customer related to the subscription.   |

| customer.first_name | the customer first name                                       |

| customer.last_name  | the customer last name                                        |

| customer.email      | the customer email                                            |

| items               | a list of items in the subscription (the original transaction)|

| items[0].name       | the name of the first item in the subscription.               |

| items[0].price      | the price of the first item in the subscription.              |

| start_date          | the start date of the subscription.                           |

| next_date           | the next transaction date of the subscription.                |

| end_date            | the end date of the subscription.                             |

| frequency           | frequency of the subscription payments.                       |

| total               | The total payment for the original transaction.               |

| currency            | The currency of the original transaction.                     |



### Formatting your message



Composing HTML mail can be much harder than one would initially think. Knowing modern HTML and CSS can be misleading.

Building a consistent, responsive look and feel involves using many of the old practices from the pre tableless days.



[**mjml**](https://github.com/mjmlio/mjml) helps you build your templates using a markup language designed to handle these issues.

It also offers an [online editor](https://mjml.io/try-it-live) and a [desktop client](https://mjmlio.github.io/mjml-app/).

### Advanced usage



- You can use Twig to achieve some advanced features. Twig offers functions such as `date`, `max` and `min` and also offers filters you can take advantage of.

- You can use Twig control flow to avoid sending emails under custom circumstances. Use `{% if variable %}...{% endif %}` so that the body (both txt and html) or the subject is empty. The application will not send emails with empty body or subject.

- If your server is configured to use sendmail, you can set the `sendmail` configuration in `config.js` file to `true` for it to send emails using sendmail.



# Development



## Testing



It is necessary to have a FoxyApi client to run the tests.



Use the `.env` file to set your environment variables.



    FOXY_DEV_REFRESH_TOKEN="your refreshToken"

    FOXY_DEV_CLIENT_SECRET="your clientSecret"

    FOXY_DEV_CLIENT_ID="your clientId"



## Dependencies



This project uses the following dependencies:



- Twig: to parse and replace variables.

- MJML: to convert mjml to html.

- FoxySDK: to interact with Foxy API.

- HTML-to-text: to strip HTML tags and build text only versions.