{"id":18683095,"url":"https://github.com/foxy/foxy-node-subscription-alert","last_synced_at":"2025-11-07T18:30:25.927Z","repository":{"id":52540195,"uuid":"335751309","full_name":"Foxy/foxy-node-subscription-alert","owner":"Foxy","description":"Sends email alerts about subscription a number of days before or after the next transaction date.","archived":false,"fork":false,"pushed_at":"2021-04-26T18:54:11.000Z","size":1050,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-16T20:49:54.516Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Foxy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-03T20:50:10.000Z","updated_at":"2021-04-26T18:54:11.000Z","dependencies_parsed_at":"2022-09-15T22:11:47.573Z","dependency_job_id":null,"html_url":"https://github.com/Foxy/foxy-node-subscription-alert","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxy%2Ffoxy-node-subscription-alert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxy%2Ffoxy-node-subscription-alert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxy%2Ffoxy-node-subscription-alert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxy%2Ffoxy-node-subscription-alert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Foxy","download_url":"https://codeload.github.com/Foxy/foxy-node-subscription-alert/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239534640,"owners_count":19654901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T10:13:44.255Z","updated_at":"2025-11-07T18:30:25.871Z","avatar_url":"https://github.com/Foxy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Foxy Subscription Alerts\n\nAllows automatically sending messages for subscribers at specific configurable dates relative to the subscriptions `nextdate`.\n\n## Usage\n\n### Configuring your Foxy credentials\n\nEdit the `config.js` folder in order to set up your credentials.\n\nThere are comments within the file explaining each field that must be filled.\n\nIn summary, you need to set up a refresToken, a clientSecret and a clientId.\nYou can find your credentials in the Foxy.io admin page:\n\n1. Go to https://foxy.io and log in.\n1. Under \"ACCOUNT\", click \"integrations.\n1. Under \"Current integrations\", click \"Get token\"\n1. Provide a project name and a project description. These fields are useful for you to remember what are these tokens used for.\n1. Copy the resulting credentials and paste in somewhere safe. \n\nIn `config.js` look for the fields with corresponding names. They sould be found in line 30. \nAdd your credentials to the respective key.\n\n### Configuring your email templates\nSending alert emails can be as easy as creating a folder and some files.\nAll you need to do is to create a folder with the messages you want to send and within this folder create your email template.\n\nHere is the simples example:\n\n    - alerts/\n        within-05/\n            body.txt\n            body.html\n\nWith this file structure in place, emails will be sent to users 5 days before their next subscription date. Also, the\nmessages will be sent in HTML (using the contents of the `.html` file) with a text fallback (with the contents of\nthe `.txt` file) for those users that for whatever reason cannot load the HTML message.\n\n\n## Creating your email alerts\n\nEach email alert is a folder within the `emails` folder.\nSimply create these folders to create new email alerts. \n\n### Sensible defaults\n\nThere are some sensible defaults already put in place.\nYou can use them as they are or use them as inspiration to create your own email templates.\n\n#### Naming your subscription alert folder\nThe way you name your folder will determine how it will be sent.\n\n- **within** Name your folders `within-NUMBER` to send an alert mail about subscriptions with next_transaction_date withing NUMBER days.\n- **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.\n\nYou can also restrict sending alerts only to `active` or `inactive` subscriptions. Prepend your folder with `active-` or `inactive-` to achieve this.\n\nHere are some examples:\n\n- `within-5`: sends alerts about subscriptions that will be renewed in 5 days.\n- `past-12` : sends alerts about subscriptions expired 12 days ago.\n- `inactive-past-2`: sends alerts about inactive subscriptions that expired 2 days ago.\n\n#### Creating your files\n\nYou need to create at least one file in each folder, called `body.txt`, `body.html` or `body.mjml`.\nThe contents of this file will be the contents of your email.\n\nYou can also create a file called `subject.txt` to customize the subject of the message.\n\n## Testing your emails\n\nBy default, Foxy Subscription Alert comes with the `testing.enabled` set to `true`. You can set it to false in the `config.js` file.\n\nWhile it is set to true, instead of sending emails to your users, it will send emails to a test account.\n\n\n### Where do I see the test emails?\n\nYou 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.\n\n#### Using Ethereal mail\nIn 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.\n\nIt 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.\n\n**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**.\nPlease, double check your SMTP configuration if you are not getting your emails.\n\n#### Using your own test email address\n\nIn 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.\n\n### Testing with testing disabled\n\nIf 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:\n\n```bash\n#send real emails\nnode index.js\n#send test emails\nnode index.js test\n```\n## Composing emails\n\nYou 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.\n\nPro-tip: consider using MJML to send responsive emails that will look nice everywhere.\n\nNote: all emails are related to a single subscription.\n\n### Using variables\n\nYou can use the [Twig templating language](https://twig.symfony.com/doc/3.x/templates.html) to compose your emails.\n\nIf you are not familiar with Twig, this might help:\n\n- Variable substitution: use double curly braces to use a variable: `Hi {{ customer.first_name }}, please confirm your email is {{ customer.email }}`.\n- 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 %}`.\n\n#### Available variables\n\nHere are the variables you will have available when writing your email templates:\n\n| Variable            | Description                                                   |\n| ------------------- | ------------------------------------------------------------- |\n| customer            | Information about the customer related to the subscription.   |\n| customer.first_name | the customer first name                                       |\n| customer.last_name  | the customer last name                                        |\n| customer.email      | the customer email                                            |\n| items               | a list of items in the subscription (the original transaction)|\n| items[0].name       | the name of the first item in the subscription.               |\n| items[0].price      | the price of the first item in the subscription.              |\n| start_date          | the start date of the subscription.                           |\n| next_date           | the next transaction date of the subscription.                |\n| end_date            | the end date of the subscription.                             |\n| frequency           | frequency of the subscription payments.                       |\n| total               | The total payment for the original transaction.               |\n| currency            | The currency of the original transaction.                     |\n\n### Formatting your message\n\nComposing HTML mail can be much harder than one would initially think. Knowing modern HTML and CSS can be misleading.\nBuilding a consistent, responsive look and feel involves using many of the old practices from the pre tableless days.\n\n[**mjml**](https://github.com/mjmlio/mjml) helps you build your templates using a markup language designed to handle these issues.\nIt also offers an [online editor](https://mjml.io/try-it-live) and a [desktop client](https://mjmlio.github.io/mjml-app/).\n### Advanced usage\n\n- 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.\n- 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.\n- 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.\n\n\n# Development\n\n## Testing\n\nIt is necessary to have a FoxyApi client to run the tests.\n\nUse the `.env` file to set your environment variables.\n\n    FOXY_DEV_REFRESH_TOKEN=\"your refreshToken\"\n    FOXY_DEV_CLIENT_SECRET=\"your clientSecret\"\n    FOXY_DEV_CLIENT_ID=\"your clientId\"\n\n## Dependencies\n\nThis project uses the following dependencies:\n\n- Twig: to parse and replace variables.\n- MJML: to convert mjml to html.\n- FoxySDK: to interact with Foxy API.\n- HTML-to-text: to strip HTML tags and build text only versions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxy%2Ffoxy-node-subscription-alert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoxy%2Ffoxy-node-subscription-alert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxy%2Ffoxy-node-subscription-alert/lists"}