{"id":19251063,"url":"https://github.com/onesignal/onesignal-rails-plugin","last_synced_at":"2026-04-17T04:33:46.539Z","repository":{"id":37925348,"uuid":"493299625","full_name":"OneSignal/onesignal-rails-plugin","owner":"OneSignal","description":null,"archived":false,"fork":false,"pushed_at":"2022-12-08T14:09:55.000Z","size":47,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":35,"default_branch":"main","last_synced_at":"2025-02-16T16:56:15.076Z","etag":null,"topics":["email","in-app-messaging","push-notifications","rails","ruby","sms"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OneSignal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-05-17T15:01:10.000Z","updated_at":"2022-09-12T15:24:02.000Z","dependencies_parsed_at":"2023-01-25T13:45:52.503Z","dependency_job_id":null,"html_url":"https://github.com/OneSignal/onesignal-rails-plugin","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Fonesignal-rails-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Fonesignal-rails-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Fonesignal-rails-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Fonesignal-rails-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OneSignal","download_url":"https://codeload.github.com/OneSignal/onesignal-rails-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240347762,"owners_count":19787230,"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","in-app-messaging","push-notifications","rails","ruby","sms"],"created_at":"2024-11-09T18:19:53.314Z","updated_at":"2025-10-18T09:19:51.324Z","avatar_url":"https://github.com/OneSignal.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eWelcome to the official OneSignal Ruby on Rails Plugin 👋\u003c/h1\u003e\n\n[![Gem Version][rgb]][rgl]\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/OneSignal/onesignal-rails-plugin/blob/master/README.md\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Documentation\" src=\"https://img.shields.io/badge/documentation-yes-brightgreen.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/OneSignal/onesignal-rails-plugin/graphs/commit-activity\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Maintenance\" src=\"https://img.shields.io/badge/Maintained%3F-yes-green.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/onesignal\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Twitter: onesignal\" src=\"https://img.shields.io/twitter/follow/onesignal.svg?style=social\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nOneSignal - the Ruby on Rails gem for OneSignal\n\nA powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com\n\nThis gem provides OneSignal integration via the Ruby on Rails ActionMailer. A custom delivery method `:onesignal` can be used to direct\nyour mailers to send emails through the OneSignal API.  Additional extensions to the mail functionality are provided to take\nadvantage of OneSignal's customer engagement platform! \n\n### 🖤 [RubyGems](https://rubygems.org/gems/onesignal-rails-plugin)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'onesignal-rails-plugin', '~\u003e 1.0.0'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install onesignal-rails-plugin\n\nOr install from Github:\n\n    $ gem \"onesignal-rails-plugin\", '~\u003e 1.0.0', git: 'git://github.com/OneSignal/onesignal-rails-plugin.git'\n\n\n## Configuration\n\nTo change all action mailers to target the OneSignal integration, edit `config/application.rb` or `config/environments/$ENVIRONMENT.rb` and \nadd/change the following to the ActionMailer configuration\n\n```ruby\nconfig.action_mailer.delivery_method = :onesignal\n```\n\nAlternatively a specific mailer can be configured to use the OneSignal delivery method.  Within your mailer\n\n```ruby\nclass MyOneSignalMailer \u003c ActionMailer::Base\n  self.delivery_method = :onesignal  \n\n  def some_email(params)\n    mail(...)\n  end\nend\n```\n\nThe OneSignal-specific configuration information can be set in either environment variables or more dynamically via code. To access your app ID\nand REST API key, please view the [documentation](https://documentation.onesignal.com/docs/accounts-and-keys).\n\nChoose one of the following ways to provide your OneSignal-specific configuration:\n1. [Using Environment Variables](#Using-Environment-Variables)\n2. [Using Application Configuration](#Using-Application-Configuration)\n3. [Using ActionMailer Configuration](#Using-ActionMailer-Configuration)\n\n### Using Environment Variables\nEnsure the OneSignal environment variables have been set, the `OneSignal::Rails::Plugin` module will pick these up automatically\n```\nONESIGNAL_APP_KEY = 'your-app-key'\nONESIGNAL_APP_ID = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'\n```\n\n### Using Application Configuration\nThe `OneSignal::Rails::Plugin` module can be configured in code by creating initializer file `config/initializers/onesignal_rails_plugin.rb` and adding the following\n(Warning: for security purposes, REST API keys should not be hardcoded into your application)\n\n```ruby\nOneSignal::Rails::Plugin.configure do |c|\n  c.app_key = 'your-app-key'\n  c.app_id = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'\nend\n```\n\n### Using ActionMailer Configuration\nFor more granular and dynamic control, you can also configure as part of the ActionMailer configuration.  Edit `config/application.rb` or\n`config/environments/$ENVIRONMENT.rb` and add the following to the ActionMailer configuration (Warning: for security purposes, REST API keys should not\nbe hardcoded into your application)\n\n```ruby\nconfig.action_mailer.onesignal_settings = {\n      app_key: 'your-app-key',\n      app_id: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'\n    }\n```\n\nSimilar to how the `delivery_method` is configured, alternatively a specific mailer can be configured to have a more granular configuration.  Within your\nmailer add the following (Warning: for security purposes, REST API keys should not be hardcoded into your application)\n\n```ruby\nclass MyOneSignalMailer \u003c ActionMailer::Base\n  self.delivery_method = :onesignal\n  self.onesignal_settings = {\n      app_key: 'your-app-key',\n      app_id: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'\n    }\n\n  def some_email(params)\n    mail(...)\n  end\nend\n```\n\n## Usage\nIf the purpose of the mailer is to generate a transactional email where the recipient, subject, and body are specified within the application,\nno additional changes are required. Your existing mailers will now send emails through your OneSignal integration!\n\n## OneSignal Extensions\nThe mail functionality is extended to include additional attributes provided by the OneSignal API.  These attributes should be specified within your\nmailer through the `mail` invocation.  See [Examples](#Examples) for examples of how to invoke `mail` to exploit these extensions.\n\n### template_id (string)\nSpecifies the id of a template created within OneSignal that should be used, rather than the body provided by your application (either via the `body`\nparameter, or defined within the view of the mailer). To use the subject within the template, specify a `OneSignal::Rails::Plugin::USE_TEMPLATE_SUBJECT` within\nthe `subject` parameter.  If the `subject` parameter is set to anything else, it will be used as the subject of the email, overriding the subject within the template. \n\n### include_external_user_ids (string array)\nA string array that lists the OneSignal external IDs that are to be the recipients of the email being sent, rather than the information provided by your application via the `to` parameter.\n\n### include_player_ids (string array)\nA string array that lists the OneSignal player IDs that are to be the recipients of the email being sent, rather than the information provided by your application via the `to` parameter.\n\n### included_segments (string array)\nA string array that lists the OneSignal segments that are to be the recipients of the email being sent, rather than the information provided by your application via the `to` parameter.\n\n### excluded_segments (string array)\nA string array that lists the OneSignal segments that will not be the recipients of the email being sent (all others will), rather than the information provided by your application via the `to` parameter.\n\n### custom_notification_args (object)\nAn object that allows for customizing the email notification that will be sent.  Each property key and value of the object will be copied into the payload of the create notification operation.\nThis allows for greater customization of notification being sent.  Example of parameters that would most likely be specified within this object:\n- *external_id:* Correlation and idempotency key.\n- *send_after:* Schedule the message for future delivery.\n- *throttle_rate_per_minute:* throttle delivery of the notification, either because throttling is not enabled at the application level or to override the application level throttling settings.\n\nNote the following are not currently supported by the Ruby API library.\n- *name:* identifier for tracking this message within the OneSignal dashboard or export analytics, not shown to the end user.\n- *disable_email_click_tracking:* When true the URLs in the email will not change to link tracking URLs and will stay the same as originally set. Best used for emails containing Universal Links.  Defaults to false.\n\nNote the following are not currently supported by the API backend.\n- *delayed_option:* Can be `timezone` or `last-active`.\n- *delivery_time_of_day:* when delayed_option=timezone, this is the time of day to deliver within the timezone.\n\n## Examples\n\nThe following shows examples of how to invoke the `mail` function within your mailer when integrated with OneSignal. Note the body is not specified as it is assumed to be generated through the view associated\nto the mailer.  This is not an exhaustive list, and different examples could be combined depending on your specific scenario.\n\n```ruby\n# Send a transactional email to a specific recipient (standard ActionMailer usage) \nmail(subject: \"email example\", from: 'no-reply@company.com', to: 'user@company.co')\n\n# Send a transactional email, relying on the OneSignal default 'from' address specified within the OneSignal dashboard\nmail(subject: \"use OneSignal default from address example\", to: 'user@company.co')\n\n# Send an email using a OneSignal template as both the subject and body of the email\nmail(subject: OneSignal::Rails::Plugin::USE_TEMPLATE_SUBJECT, to: 'user@company.co', template_id: '00000000-0000-0000-0000-000000000000')\n\n# Send an email using a OneSignal template, overriding the subject specified on the template\nmail(subject: \"template subject override example\", to: 'user@company.co', template_id: '00000000-0000-0000-0000-000000000000')\n\n# Send an email to a list of OneSignal users via their external user IDs\nmail(subject: \"external id example\", include_external_user_ids: [\"User123\", \"User456\"])\n\n# Send an email to a list of OneSignal users via their player IDs\nmail(subject: \"player id example\", include_player_ids: [\"00000000-0000-0000-0000-000000000000\", \"11111111-1111-1111-1111-111111111111\"])\n\n# Send an email to a list of OneSignal users that are within the provided segments\nmail(subject: \"include segments example\", included_segments: [\"Subscribed Users\"])\n\n# Send an email to the app's audience, excluding the provided segments.\nmail(subject: \"excluded segments example\", excluded_segments: [\"Engaged Users\"])\n\n# Send an email with the external_id, which ensures idempotency\nmail(subject: \"set external_id example\", to: 'user@company.co', custom_notification_args: { 'external_id' =\u003e \"00000000-0000-0000-0000-000000000000\" })\n\n# Send an email after a certain time\nmail(subject: \"send after example\", to: 'user@company.co', custom_notification_args: { 'send_after' =\u003e \"2022-05-19 15:20:00 GMT-0400\" })\n\n# Send an email with rate throttling\nmail(subject: \"throttle rate example\", to: 'user@company.co', custom_notification_args: { 'throttle_rate_per_minute' =\u003e 1 })\n```\n\n## Testing\n\nTo run the rspec tests\n\n    $ bundle exec rspec --format documentation\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License][mit].\n\n[rgb]: https://img.shields.io/gem/v/onesignal-rails-plugin.svg\n[rgl]: https://rubygems.org/gems/onesignal-rails-plugin\n[osa]: https://documentation.onesignal.com/reference/\n[mit]: http://opensource.org/licenses/MIT\n\n## Author\n\n* Website: https://onesignal.com\n* Twitter: [@onesignal](https://twitter.com/onesignal)\n* Github: [@OneSignal](https://github.com/OneSignal)\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel free to check [issues page](https://github.com/OneSignal/onesignal-rail-plugin/issues).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n## 📝 License\n\nCopyright © 2022 [OneSignal](https://github.com/OneSignal).\u003cbr /\u003e\nThis project is [MIT](https://opensource.org/licenses/MIT) licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonesignal%2Fonesignal-rails-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonesignal%2Fonesignal-rails-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonesignal%2Fonesignal-rails-plugin/lists"}