{"id":15288778,"url":"https://github.com/jereinhardt/feste","last_synced_at":"2025-04-13T08:11:26.640Z","repository":{"id":55643994,"uuid":"106875226","full_name":"jereinhardt/feste","owner":"jereinhardt","description":"Email subscription management for Rails applications","archived":false,"fork":false,"pushed_at":"2020-12-21T15:16:27.000Z","size":255,"stargazers_count":11,"open_issues_count":4,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-21T10:05:17.809Z","etag":null,"topics":["email","rails","ruby","subscription"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jereinhardt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-13T21:31:30.000Z","updated_at":"2021-10-06T18:52:58.000Z","dependencies_parsed_at":"2022-08-15T05:20:41.359Z","dependency_job_id":null,"html_url":"https://github.com/jereinhardt/feste","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/jereinhardt%2Ffeste","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jereinhardt%2Ffeste/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jereinhardt%2Ffeste/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jereinhardt%2Ffeste/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jereinhardt","download_url":"https://codeload.github.com/jereinhardt/feste/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681491,"owners_count":21144700,"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":["email","rails","ruby","subscription"],"created_at":"2024-09-30T15:53:09.402Z","updated_at":"2025-04-13T08:11:26.616Z","avatar_url":"https://github.com/jereinhardt.png","language":"Ruby","readme":":email: Feste is an easy way to give your users the ability to manage email subscriptions in your Rails application.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'feste'\n```\n\nAnd then execute:\n\n    $ bundle install\n    $ rails generate feste:install\n    $ rake db:migrate\n\nOnce installed, you will need to mount Feste in your application.\n\n```ruby\n# config/routes.rb\nmount Feste::Engine =\u003e \"/email-subscriptions\", as: \"feste\"\n```\n\n## Configuration\n\nFeste organizes subscribable emails by separating them into categories that you define (see \u003ca href=\"#mailer\"\u003eMailer\u003c/a\u003e for more details).  This requires an array of available categories (represented by symbols) to be provided to the `categories` configuration.\n\nOut of the box, Feste allows your users to manage their subscriptions from a url in their email, which includes an identifying token.  If you would like for them to be able to do so from within your application, you will need to provide a method for identifying the currently logged in user.  Luckily, Feste provides authentication adapters for applications that use Devise and Clearance to manage user sessions.  Otherwise, you can provide a Proc to the `authenticate_with` option.\n\nOptionally, you can set the attribute your user model(s) use(s) to reference a user's email address (`email_source`) and the host that is used by the `subscriptions_url` helper (`host`).\n\n```ruby\n# initializers/feste.rb\nauthentication_method = Proc.new do |controller|\n  ::User.find_by(id: controller.session[:user_id])\nend\n\nFeste.configure do |config|\n  # set your category names\n  config.categories = [:marketing_emails, :reminder_emails]\n  # for applications that use clearance\n  config.authenticate_with = :clearance\n  # for applications that use devise\n  config.authenticate_with = :devise\n  # for applications that use custom authentication\n  config.authenticate_with = authentication_method\n  # set the email attribute of your user model\n  config.email_source = :email\n  # set the host for subscription_url\n  config.host = ActionMailer::Base.default_url_options[:host]\n  # set callbacks\n  config.callback_handler = FesteCallbackHandler.new\nend\n```\n## Usage\n\n### Model\n\nIn the model that holds your users' data, include `Feste::User`.\n\n```ruby\nclass User \u003c ApplicationRecord\n  include Feste::User\nend\n```\n\nThis will give your user model a `has_many` relationship to `subscriptions`.  Since this relationship is polymorphic, your can include the `Feste::User` module in multiple models.  \n\n### Mailer\n\nIn your mailer, include the `Feste::Mailer` module.\n\nFeste keeps track of email subscriptions by grouping mailer actions into categories that you define.  Your users will not be able to subscribe or unsubscribe to emails until you assign specific actions to a category.  In order to do this, you can call the `categorize` method within your mailer.  Doing so will automatically assign all actions in that mailer to the category you provide through the `as` option.\n\nWhen calling the `mail` method within an action, make sure to explicitly state which user the subscription should be applied to using the `subscriber` option.\n\n```ruby\nclass CouponMailer \u003c ApplicationMailer\n  include Feste::Mailer\n\n  categorize as: :marketing_emails\n\n  def send_coupon(user)\n    mail(to: user.email, from: \"support@here.com\", subscriber: user)\n  end\nend\n```\n\nIf you only want to categorize specific actions in a mailer, you can do so by listing those actions in an array as your first arguement.\n\n```ruby\nclass CouponMailer \u003c ApplicationMailer\n  include Feste::Mailer\n\n  categorize [:send_coupon], as: :marketing_emails\n  categorize [:send_coupon_reminder], as: :reminder_emails\n\n  def send_coupon(user)\n    mail(to: user.email, from: \"support@here.com\", subscriber: user)\n  end\n\n  def send_coupon_reminder(user)\n    mail(to: user.email, from: \"support@here.com\", subscriber: user)\n  end\nend\n```\n\n### View\n\n#### Mailer View\n\nIn our view file, you can use the helper method `subscription_url` to link to the page where users can manage their subscriptions.\n\n```html\n\u003ca href=\"\u003c%= subscription_url %\u003e\"\u003eclick here to unsubscribe\u003c/a\u003e \n```\n\nWhen a user clicks this link, they are taken to a page that allows them to choose which emails (by category) they would like to keep receiving, and which ones they would like to unsubscribe to. \n\n#### Application View\n\nThe route to the subscriptions page is the root of the feste engine.  You can link to this page from anywhere in your app using the `feste.subscriptions_url` helper (assuming the engine is mounted as 'feste').  When a logged in user visits this page from your application, they will be authenticated through the method which you provide in the configuration, and shown their email subscriptions.\n\n### Human Readable Category Names\n\nIn order to create category names that are human readable, add a `feste.categories`section to your i18n `locales` files.  Create keys in this section that correspond to the `categories` configuration.\n\n```yml\n# config/locales/en.yml\n\nen:\n  feste:\n    categories:\n      marketing_emails: Marketing Emails\n      reminder_emails: Reminder Emails\n```\n\n### When not to use\n\nIt is recommended you DO NOT include any important emails, such as password reset emails, into a subscribable category.  It is also recommended you do not include the subscription link in any email that is sent to multiple recipients.  Though Feste comes with some security measures, it is assumed that each email is intended for only one recipient, and the `subscription_url` helper leads to a subsciption page meant only for that recipient.  Exposing this page to other users may allow them to change subscription preferences for someone else's account.\n\n## Callbacks\n\nIf you would like to create callbacks for when a user unsubscribes or resubscribes to a mailing list, you can do so by creating a callback handler.  Callback handlers should be objects with two instance methods: `unsubscribe` and `resubscribe`.  You can register an instance of this object as your callback handler with the `callback_handler` configuration option.\n\n```ruby\n# config/initializers/feste.rb\n\nclass CallbackHandler\n  def unsubscribe(event)\n    # This method is called whenever a user unsubscribes from an mailing list they were previously subscribed to.\n    event[:controller] # the instance of the controller\n    event[:subscriber] # the user that unsubscribed\n  end\n\n  def resubscribe(event)\n    # This method is called whenever a user subscribes to a mailing list they were previously unsubscribed to.\n  end\nend\n\nFeste.configure do |config|\n  config.callback_handler = CallbackHandler.new\nend\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/jereinhardt/feste.\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\nl create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjereinhardt%2Ffeste","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjereinhardt%2Ffeste","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjereinhardt%2Ffeste/lists"}