{"id":13484583,"url":"https://github.com/mailboxer/mailboxer","last_synced_at":"2025-05-15T07:02:43.685Z","repository":{"id":422656,"uuid":"1449820","full_name":"mailboxer/mailboxer","owner":"mailboxer","description":"A Rails gem to send messages inside a web application","archived":false,"fork":false,"pushed_at":"2024-04-11T22:08:07.000Z","size":687,"stargazers_count":1643,"open_issues_count":151,"forks_count":462,"subscribers_count":46,"default_branch":"master","last_synced_at":"2025-04-07T01:11:17.588Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/mailboxer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-03-07T11:55:43.000Z","updated_at":"2025-03-31T14:31:59.000Z","dependencies_parsed_at":"2023-07-05T14:53:01.816Z","dependency_job_id":"62e4c2a2-754a-4f84-8ef9-8a76dafa0c21","html_url":"https://github.com/mailboxer/mailboxer","commit_stats":{"total_commits":385,"total_committers":78,"mean_commits":4.935897435897436,"dds":0.6805194805194805,"last_synced_commit":"3e148858879110c3258b46152b11e5bfc514dc04"},"previous_names":["ging/mailboxer"],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailboxer%2Fmailboxer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailboxer%2Fmailboxer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailboxer%2Fmailboxer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailboxer%2Fmailboxer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mailboxer","download_url":"https://codeload.github.com/mailboxer/mailboxer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852112,"owners_count":21171839,"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-07-31T17:01:26.543Z","updated_at":"2025-04-14T08:56:32.089Z","avatar_url":"https://github.com/mailboxer.png","language":"Ruby","readme":"# Mailboxer [![Build Status](https://travis-ci.org/mailboxer/mailboxer.svg?branch=master)](https://travis-ci.org/mailboxer/mailboxer) [![Gem Version](https://badge.fury.io/rb/mailboxer.png)](http://badge.fury.io/rb/mailboxer) [![](https://gemnasium.com/ging/mailboxer.png)](https://gemnasium.com/ging/mailboxer)\n\nThis project is based on the need for a private message system for [ging\n/ social\\_stream](https://github.com/ging/social_stream). Instead of creating our core message system heavily\ndependent on our development, we are trying to implement a generic and\npotent messaging gem.\n\nAfter looking for a good gem to use we noticed the lack of messaging gems\nand functionality in them. Mailboxer tries to fill this void delivering\na powerful and flexible message system. It supports the use of\nconversations with two or more participants, sending notifications to\nrecipients (intended to be used as system notifications “Your picture has\nnew comments”, “John Doe has updated his document”, etc.), and emailing the\nmessageable model (if configured to do so). It has a complete implementation\nof a `Mailbox` object for each messageable with `inbox`, `sentbox` and\n`trash`.\n\nThe gem is constantly growing and improving its functionality. As it is\nused with our parallel development [ging / social\\_stream](https://github.com/ging/social_stream) we are finding and fixing bugs continously. If you want\nsome functionality not supported yet or marked as TODO, you can create\nan [issue](https://github.com/ging/mailboxer/issues) to ask for it. It will be great feedback for us, and we\nwill know what you may find useful in the gem.\n\nMailboxer was born from the great, but outdated, code from [lpsergi /\nacts_as_messageable](https://github.com/psergi/acts_as_messageable).\n\nWe are now working to make exhaustive documentation and some wiki\npages in order to make it even easier to use the gem to its full potential.\nPlease, give us some time if you find something missing or [ask for\nit](https://github.com/ging/mailboxer/issues).  You can also find us on the [Gitter room for this repo](https://gitter.im/mailboxer/mailboxer).  Join us there to talk.\n\nInstallation\n------------\n\nAdd to your Gemfile:\n\n```ruby\ngem 'mailboxer'\n```\n\nThen run:\n\n```sh\n$ bundle install\n```\n\nRun install script:\n\n```sh\n$ rails g mailboxer:install\n```\n\nAnd don't forget to migrate your database:\n\n```sh\n$ rake db:migrate\n```\n\nYou can also generate email views:\n\n```sh\n$ rails g mailboxer:views\n```\n\nUpgrading\n---------\n\nIf upgrading from 0.11.0 to 0.12.0, run the following generators:\n\n```sh\n$ rails generate mailboxer:namespacing_compatibility\n$ rails generate mailboxer:install -s\n```\n\nThen, migrate your database:\n\n```sh\n$ rake db:migrate\n```\n\n## Requirements \u0026 Settings\n\n### Emails\n\nWe are now adding support for sending emails when a Notification or a Message is sent to one or more recipients. You should modify the mailboxer initializer (/config/initializer/mailboxer.rb) to edit these settings:\n\n```ruby\nMailboxer.setup do |config|\n  #Enables or disables email sending for Notifications and Messages\n  config.uses_emails = true\n  #Configures the default `from` address for the email sent for Messages and Notifications of Mailboxer\n  config.default_from = \"no-reply@dit.upm.es\"\n  ...\nend\n```\n\nYou can change the way in which emails are delivered by specifying a custom implementation of notification and message mailers:\n\n```ruby\nMailboxer.setup do |config|\n  config.notification_mailer = CustomNotificationMailer\n  config.message_mailer = CustomMessageMailer\n  ...\nend\n```\n\nIf you have subclassed the Mailboxer::Notification class, you can specify the mailers using a member method:\n\n```ruby\nclass NewDocumentNotification \u003c Mailboxer::Notification\n  def mailer_class\n    NewDocumentNotificationMailer\n  end\nend\n\nclass NewCommentNotification \u003c Mailboxer::Notification\n  def mailer_class\n    NewDocumentNotificationMailer\n  end\nend\n```\n\nOtherwise, the mailer class will be determined by appending 'Mailer' to the mailable class name.\n\n### User identities\n\nUsers must have an identity defined by a `name` and an `email`. We must ensure that Messageable models have some specific methods. These methods are:\n\n```ruby\n#Returning any kind of identification you want for the model\ndef name\n  return \"You should add method :name in your Messageable model\"\nend\n```\n\n```ruby\n#Returning the email address of the model if an email should be sent for this object (Message or Notification).\n#If no mail has to be sent, return nil.\ndef mailboxer_email(object)\n  #Check if an email should be sent for that object\n  #if true\n  return \"define_email@on_your.model\"\n  #if false\n  #return nil\nend\n```\n\nThese names are explicit enough to avoid colliding with other methods, but as long as you need to change them you can do it by using mailboxer initializer (/config/initializer/mailboxer.rb). Just add or uncomment the following lines:\n\n```ruby\nMailboxer.setup do |config|\n  # ...\n  #Configures the methods needed by mailboxer\n  config.email_method = :mailboxer_email\n  config.name_method = :name\n  config.notify_method = :notify\n  # ...\nend\n```\n\nYou may change whatever you want or need. For example:\n\n```ruby\nconfig.email_method = :notification_email\nconfig.name_method = :display_name\nconfig.notify_method = :notify_mailboxer\n```\n\nWill use the method `notification_email(object)` instead of `mailboxer_email(object)`, `display_name` for `name` and `notify_mailboxer` for `notify`.\n\nUsing default or custom method names, if your model doesn't implement them, Mailboxer will use dummy methods so as to notify you of missing methods rather than crashing.\n\n## Preparing your models\n\nIn your model:\n\n```ruby\nclass User \u003c ActiveRecord::Base\n  acts_as_messageable\nend\n```\n\nYou are not limited to the User model. You can use Mailboxer in any other model and use it in several different models. If you have ducks and cylons in your application and you want to exchange messages as if they were the same, just add `acts_as_messageable` to each one and you will be able to send duck-duck, duck-cylon, cylon-duck and cylon-cylon messages. Of course, you can extend it for as many classes as you need.\n\nExample:\n\n```ruby\nclass Duck \u003c ActiveRecord::Base\n  acts_as_messageable\nend\n```\n\n```ruby\nclass Cylon \u003c ActiveRecord::Base\n  acts_as_messageable\nend\n```\n\n## Mailboxer API\n\n### Warning for version 0.8.0\nVersion 0.8.0 sees `Messageable#read` and `Messageable#unread` renamed to `mark_as_(un)read`, and `Receipt#read` and `Receipt#unread` to `is_(un)read`. This may break existing applications, but `read` is a reserved name for Active Record, and the best pratice in this case is simply avoid using it.\n\n### How can I send a message?\n\n```ruby\n#alfa wants to send a message to beta\nalfa.send_message(beta, \"Body\", \"subject\")\n```\n\n### How can I read the messages of a conversation?\n\nAs a messageable, what you receive are receipts, which are associated with the message itself. You should retrieve your receipts for the conversation and get the message associated with them.\n\nThis is done this way because receipts save the information about the relation between messageable and the messages: is it read?, is it trashed?, etc.\n\n```ruby\n#alfa gets the last conversation (chronologically, the first in the inbox)\nconversation = alfa.mailbox.inbox.first\n\n#alfa gets it receipts chronologically ordered.\nreceipts = conversation.receipts_for alfa\n\n#using the receipts (i.e. in the view)\nreceipts.each do |receipt|\n  ...\n  message = receipt.message\n  read = receipt.is_unread? #or message.is_unread?(alfa)\n  ...\nend\n```\n\n### How can I reply to a message?\n\n```ruby\n#alfa wants to reply to all in a conversation\n#using a receipt\nalfa.reply_to_all(receipt, \"Reply body\")\n\n#using a conversation\nalfa.reply_to_conversation(conversation, \"Reply body\")\n```\n\n```ruby\n#alfa wants to reply to the sender of a message (and ONLY the sender)\n#using a receipt\nalfa.reply_to_sender(receipt, \"Reply body\")\n```\n\n### How can I delete a message from trash?\n\n```ruby\n#delete conversations forever for one receipt (still in database)\nreceipt.mark_as_deleted\n\n#you can mark conversation as deleted for one participant\nconversation.mark_as_deleted participant\n\n#Mark the object as deleted for messageable\n#Object can be:\n  #* A Receipt\n  #* A Conversation\n  #* A Notification\n  #* A Message\n  #* An array with any of them\nalfa.mark_as_deleted conversation\n\n# get available message for specific user\nconversation.messages_for(alfa)\n```\n### How can I retrieve my conversations?\n\n```ruby\n#alfa wants to retrieve all his conversations\nalfa.mailbox.conversations\n\n#A wants to retrieve his inbox\nalfa.mailbox.inbox\n\n#A wants to retrieve his sent conversations\nalfa.mailbox.sentbox\n\n#alfa wants to retrieve his trashed conversations\nalfa.mailbox.trash\n```\n\n### How can I paginate conversations?\n\nYou can use Kaminari to paginate the conversations as normal. Please, make sure you use the last version as mailboxer uses `select('DISTINCT conversations.*')` which was not respected before Kaminari 0.12.4 according to its changelog. Working correctly on Kaminari 0.13.0.\n\n```ruby\n#Paginating all conversations using :page parameter and 9 per page\nconversations = alfa.mailbox.conversations.page(params[:page]).per(9)\n\n#Paginating received conversations using :page parameter and 9 per page\nconversations = alfa.mailbox.inbox.page(params[:page]).per(9)\n\n#Paginating sent conversations using :page parameter and 9 per page\nconversations = alfa.mailbox.sentbox.page(params[:page]).per(9)\n\n#Paginating trashed conversations using :page parameter and 9 per page\nconversations = alfa.mailbox.trash.page(params[:page]).per(9)\n```\n\nYou can take a look at the full documentation for Mailboxer in [rubydoc.info](http://rubydoc.info/gems/mailboxer/frames).\n\n## Do you want to test Mailboxer?\n\nThanks to [Roman Kushnir (@RKushnir)](https://github.com/RKushnir/) you can test Mailboxer with this [sample app](https://github.com/RKushnir/mailboxer-app).\n\n## I need a GUI!\n\nIf you need a GUI you should take a look at these links:\n\n* The wiki page [GUI Example on a real application](https://github.com/ging/mailboxer/wiki/GUI-Example-on-a-real-application).\n\n## Contributors\n* [Roendal](https://github.com/ging/mailboxer/commits/master?author=Roendal) (Eduardo Casanova)\n* [dickeyxxx](https://github.com/ging/mailboxer/commits/master?author=dickeyxxx) (Jeff Dickey)\n* [RKushnir](https://github.com/ging/mailboxer/commits/master?author=RKushnir) (Roman Kushnir)\n* [amaierhofer](https://github.com/ging/mailboxer/commits/master?author=amaierhofer) (Andreas Maierhofer)\n* [tonydewan](https://github.com/ging/mailboxer/commits/master?author=tonydewan) (Tony Dewan)\n* [plentz](https://github.com/ging/mailboxer/commits/master?author=plentz) (Diego Plentz)\n* [laserlemon](https://github.com/ging/mailboxer/commits/master?author=laserlemon) (Steve Richert)\n* [daveworth](https://github.com/ging/mailboxer/commits/master?author=daveworth) (Dave Worth)\n* [rafaelgg](https://github.com/ging/mailboxer/commits/master?author=rafaelgg) (Rafael Garcia)\n* [joshblour](https://github.com/ging/mailboxer/commits/master?author=joshblour) (joshblour)\n* [iamdeuterium](https://github.com/ging/mailboxer/commits/master?author=iamdeuterium) (iamdeuterium)\n* [daveworth](https://github.com/ging/mailboxer/commits/master?author=daveworth) (Dave Worth)\n* [parndt](https://github.com/ging/mailboxer/commits/master?author=parndt) (Philip Arndt)\n* [atd](https://github.com/ging/mailboxer/commits/master?author=atd) (Antonio Tapiador)\n* [mobilutz](https://github.com/ging/mailboxer/commits/master?author=mobilutz) (Lutz)\n* [bennick](https://github.com/ging/mailboxer/commits/master?author=bennick) (Ryan Bennick)\n* [rjst](https://github.com/ging/mailboxer/commits/master?author=rjst) (Ricardo Trindade)\n* [fabianoalmeida](https://github.com/ging/mailboxer/commits/master?author=fabianoalmeida) (Fabiano Almeida)\n* [supremebeing7](https://github.com/ging/mailboxer/commits/master?author=supremebeing7) (Mark J. Lehman)\n* [searsaw](https://github.com/mailboxer/mailboxer/commits/master?author=searsaw) (Alex Sears)\n* [joshblour](https://github.com/mailboxer/mailboxer/commits/master?author=joshblour) (Yonah Forst)\n","funding_links":[],"categories":["Ruby","Social Networking","Web 后端"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailboxer%2Fmailboxer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmailboxer%2Fmailboxer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailboxer%2Fmailboxer/lists"}