Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/benprew/pony

The express way to send mail from Ruby.
https://github.com/benprew/pony
Last synced: about 2 months ago
JSON representation
The express way to send mail from Ruby.
Host: GitHub
URL: https://github.com/benprew/pony
Owner: benprew
Fork: true (adamwiggins/pony)
Created: 2009-07-27T22:46:36.000Z (over 15 years ago)
Default Branch: master
Last Pushed: 2024-03-28T20:11:01.000Z (8 months ago)
Last Synced: 2024-05-17T04:43:55.142Z (6 months ago)
Language: Ruby
Homepage:
Size: 144 KB
Stars: 1,145
Watchers: 25
Forks: 51
Open Issues: 2
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

awesome-ruby - Pony - The express way to send mail from Ruby. (Email)
README

        # Pony, the express way to send email in Ruby #

## Overview ##

Ruby no longer has to be jealous of PHP's mail() function, which can send an email in a single command.

    Pony.mail(:to => '[email protected]', :from => '[email protected]', :subject => 'hi', :body => 'Hello there.')

    Pony.mail(:to => '[email protected]', :html_body => '
Hello there!', :body => "In case you can't read html, Hello there.")

    Pony.mail(:to => '[email protected]', :cc => '[email protected]', :from => '[email protected]', :subject => 'hi', :body => 'Howsit!')

Any option key may be omitted except for ```:to```.  See List Of Options section for the complete list.

## Transport ##

Pony uses ```/usr/sbin/sendmail``` to send mail if it is available, otherwise it uses SMTP to localhost.

This can be overridden if you specify a via option:

    Pony.mail(:to => '[email protected]', :via => :smtp) # sends via SMTP

    Pony.mail(:to => '[email protected]', :via => :sendmail) # sends via sendmail

You can also specify options for SMTP:

    Pony.mail({

      :to => '[email protected]',

      :via => :smtp,

      :via_options => {

        :address        => 'smtp.yourserver.com',

        :port           => '25',

        :user_name      => 'user',

        :password       => 'password',

        :authentication => :plain, # :plain, :login, :cram_md5, no auth by default

        :domain         => "localhost.localdomain" # the HELO domain provided by the client to the server

      }

    })

Gmail example (with TLS/SSL)

    Pony.mail({

      :to => '[email protected]',

      :via => :smtp,

      :via_options => {

        :address              => 'smtp.gmail.com',

        :port                 => '587',

        :enable_starttls_auto => true,

        :user_name            => 'user',

        :password             => 'password_see_note',

        :authentication       => :plain, # :plain, :login, :cram_md5, no auth by default

        :domain               => "localhost.localdomain" # the HELO domain provided by the client to the server

      }

    })

Note: If you use 2 step verification, you will have to generate an application specific password and NOT use your normal password - see https://support.google.com/accounts/answer/185833?hl=en

And options for Sendmail:

    Pony.mail({

      :to => '[email protected]',

      :via => :sendmail,

      :via_options => {

        :location  => '/path/to/sendmail', # defaults to 'which sendmail' or '/usr/sbin/sendmail' if 'which' fails

        :arguments => '-t' # -t and -i are the defaults

      }

    })

If you're using smtp, set ```:arguments => ''```.

## Attachments ##

You can attach a file or two with the :attachments option:

    Pony.mail(..., :attachments => {"foo.zip" => File.read("path/to/foo.zip"), "hello.txt" => "hello!"})

Note: An attachment's mime-type is set based on the filename (as dictated by the ruby gem mime-types).  So 'foo.pdf' has a mime-type of 'application/pdf'

## Custom Headers ##

Pony allows you to specify custom mail headers

    Pony.mail(

      :to => '[email protected]',

      :headers => { "List-ID" => "...", "X-My-Custom-Header" => "what a cool custom header" }

    )

Add additional options for headers in each part of letter (text, html)

    Pony.mail(

      :body => 'test',

      :html_body => 'What do you know, Joe?',

      :attachments => {"foo.txt" => "content of foo.txt"},

      :body_part_header => { content_disposition: "inline" }

    )

This will add option ```'Content-Disposition: inline'``` for text part header of letter.

Also you can add additional options for html part of latter, e.g.:

    :html_body_part_header => { content_disposition: "inline" }

## List Of Options ##

You can get a list of options from Pony directly:

    Pony.permissable_options

Options passed pretty much directly to Mail

    attachments # see Attachments section

    bcc

    body # the plain text body

    body_part_header # see Custom headers section

    cc

    charset # In case you need to send in utf-8 or similar

    content_type

    from

    headers # see Custom headers section

    html_body # for sending html-formatted email

    html_body_part_header # see Custom headers section

    message_id

    reply_to

    sender  # Sets "envelope from" (and the Sender header)

    smtp_envelope_to

    subject

    text_part_charset # for multipart messages, set the charset of the text part

    to

Other options

    via # :smtp or :sendmail, see Transport section

    via_options # specify transport options, see Transport section

### Default Options ###

Default options can be set so that they don't have to be repeated. The default options you set will be overriden by any options you pass in to Pony.mail()

    Pony.options = { :from => '[email protected]', :via => :smtp, :via_options => { :host => 'smtp.yourserver.com' } }

    Pony.mail(:to => 'foo@bar') # Sends mail to foo@bar from [email protected] using smtp

    Pony.mail(:from => '[email protected]', :to => 'foo@bar') # Sends mail to foo@bar from [email protected] using smtp

### Override Options ###

Override options can be set so that the override value is always be used, even if a different value is passed in to Pony.options() or Pony.mail(). This can be used to configure a development or staging environment.

    Pony.override_options = { :to => '[email protected]' }

    Pony.mail(:to => 'foo@bar') # Sends mail to [email protected] instead of foo@bar

## Testing/Debugging Aids ##

[![Build Status](https://travis-ci.org/benprew/pony.svg?branch=master)](https://travis-ci.org/benprew/pony)

### Subject prefix ###

Prepends a string to the subject line.  This is used to identify email sent from a specific environment.

    Pony.subject_prefix('Prefix:')

### Append options to body ###

Append the options passd into Pony.mail to the body of the email.  Useful for debugging.

    Pony.append_inputs

### Using Pony with Testing or Spec'ing Libraries ###

As pony relies on mail to send the mails, you can also use its TestMailer in your tests.

    Pony.override_options = { :via => :test }

    Pony.mail(:to => 'foo@bar')

    Mail::TestMailer.deliveries.length

    => 1

For further examples see the [corresponding section of mail's readme](https://github.com/mikel/mail#using-mail-with-testing-or-specing-libraries)

## Help ##

If you need help using Pony, or it looks like you've found a bug,

email [email protected].  The full forum is

https://groups.google.com/forum/#!forum/ponyrb

### Meta ###

* Released under the [MIT License](http://www.opensource.org/licenses/mit-license.php)

* [Homepage](http://github.com/benprew/pony)

* Mailing List: [email protected]

## Authors ##

*  Adam Wiggins  [@adamwiggins](https://github.com/adamwiggins)

*  Andrea Talbot

*  Ben Prew  [@benprew](https://github.com/benprew)

*  Cameron Matheson  [@cmatheson](https://github.com/cmatheson)

*  Carl Hörberg  [@carlhoerberg](https://github.com/carlhoerberg)

*  Christian Haase  [@krissi](https://github.com/krissi)

*  Daniel Lopes  [@danielvlopes](https://github.com/danielvlopes)

*  Doug Hammond  [@dslh](https://github.com/dslh)

*  Fabó Márton

*  Hiroshi Saito  [@hiroshi](https://github.com/hiroshi)

*  Kalin Harvey

*  MIKAMI Yoshiyuki  [@yoshuki](https://github.com/yoshuki)

*  Mathieu Martin  [@webmat](https://github.com/webmat)

*  Michael Durrant  [@durrantm](https://github.com/durrantm)

*  Michal Kwiatkowski  [@mkwiatkowski](https://github.com/mkwiatkowski)

*  Nami-Doc

*  Neil Middleton  [@neilmiddleton](https://github.com/neilmiddleton)

*  Neil Mock  [@neilmock](https://github.com/neilmock)

*  Nickolas Means  [@nmeans](https://github.com/nmeans)

*  Othmane Benkirane  [@anaothmane](https://github.com/anaothmane)

*  Rich Meyers  [@richmeyers](https://github.com/richmeyers)

*  Roman Franko  [@roman-franko](https://github.com/roman-franko)

*  Ryan Malecky  [@rmalecky](https://github.com/rmalecky)

*  Seamus Abshere  [@seamusabshere](https://github.com/seamusabshere)

*  Stephen Celis  [@stephencelis](https://github.com/stephencelis)

*  Steve Root  [@steveroot](https://github.com/steveroot)

*  arunthampi  [@arunthampi](https://github.com/arunthampi)

*  rick  [@rick](https://github.com/rick)

*  rohit  [@rohit](https://github.com/rohit)

## Changelog ##

#### 1.13.2 ####

* Bump rake version, bump outdated gems (rspec and mini_mime)

#### 1.13 ####

* fix bug: suppress potential error message from "which"

* fix bug: Add support for passing empty hashes as attachment

#### 1.12 ####

* fix bug: NoMethodError when using mail 2.7.0

#### 1.11 ####

* Improved handling of mails with both text and html bodies and attachments

#### 1.10 ####

* Add ```subject_prefix```, ```append_options``` and ```override_options```

#### 1.9 ####

* Allow options to be queried from the gem

#### 1.8 ####

* Add additional options for headers in each part of letter

#### 1.7 ####

* Better default content_type with attachments

#### 1.6 ####

* Unknown options are passed directly to mail to handle.  Remove deprecated syntax

#### 1.5.1 ####

* Loosen mail dependency to >= 2.0 instead of > 2.0

#### 1.5 ####

* Specify content-id of attachments as filename@hostname

#### 1.4.1 ####

* Update gemfile

#### 1.4 ####

* Updated docs

#### 1.3 ####

* Add new option ```:text_part_charset```, which allows you to specify the charset for the text portion

#### 1.2 ####

* Remove limitations on :via, and let mail handle it (this means you can say things like :via => test)

* Add reply-to option and a bundler file

#### 1.1 ####

* Add default options

#### 1.0 ####

* Convert to using Mail as the mail-generation backend, instead of TMail

#### 0.9.1 ####

* provide the ability to set custom mail headers with something like:

	Pony.mail(:headers => {"List-ID" => "..."})

* provide the ability to set the Message-Id from Pony.mail

#### 0.9 ####

* merge in kalin's fixes to use tmail.destinations instead of trying to parse tmail.to, tmail.cc and tmail.bcc.  New specs to test functionality

#### 0.8 ####

* Fix bug that was allowing nil :bcc and :cc options to be passed to smtp

#### 0.7 ####

* Pass :cc and :bcc options to sendmail appropriately

#### 0.6 ####

* Add :bcc capability

* Add :charset capability

* Add complete list of options to readme

* fix bug: readme examples

#### 0.5 ####

* default location of sendmail to /usr/sbin/sendmail if sendmail not in path

* fix bug: README not showing password option (listed as pass)

#### 0.4.1 ####

* Add :cc capability

* fix bug: resolve body not displaying when attachments sent

#### 0.4 ####

* Implemented file attachments option

* use TLS if :tls => true