Google Apps migration API mail delivery
=======================================
for Mail Gem
------------
By Timo van Prooijen
- v0.0.1


This gem is extracted, with permission, from a project I'm doing for one of my clients.

Introduction
------------

'Google Apps migration API mail delivery method' is an extension for the Mail gem. It provides a delivery method based on the the Google Apps migration API. This API is only available for organization who uses Google Apps for Business, Education or ISPs. (unfortunately not for Gmail or the free edition)

Whenever your application needs to automatically generate *complex* emails, which have to be manually approved before they can get sent out; You can make life easy with this gem in combination with google apps. Instead of delivering the email the email will be stored in a, preconfigured users *DRAFTS* folder. You could also integrate this gem with a CRM system in order to load templates for further manual completion.

Since this gem uses the Google Apps *migration* API; It is also possible to place messages in the users *SENT* or *INBOX* folder. However a proper use-case hasn't crossed my mind yet. (except for practical jokes)

Authentication is either done with the credentials of the domain administrator or the user into who's mailbox you are going to migrate.When authenticating as an user, an administrator has to enable the API for that user first. This can be done in the Google Apps control panel for your domain.

perhaps needless to say: Keep your codebase on a safe place when it contains any plain-text google apps account credentials!

A possible future extension would be the use of *oAuth* for client authentication. (Useful if the user of your application is also the owner of the account you're *migrating* into )


Example
-----

Gemfile:

    source "http://rubygems.org"
    gem 'gomig_mail_delivery'


edit example.rb with your domain credentials:
    
```ruby
require 'gomig_mail_delivery'

Mail.defaults do
  delivery_method Mail::GomigMailDelivery::Agent, {
    :domain                => '<your domain>.<tld>',
    :login_account         => '<admin_or_user_acount>',
    :password              => '<passwordD>',
    :to_account            => '<target_account>',
    :mail_item_property    => 'IS_DRAFT' # optional. other options: IS_INBOX, IS_SENT
  }
end

mail = Mail.deliver do
  from    'sender@domain.tld'
  date    Time.now
  to      'recipient name <recipient@domain.tld>'
  subject 'I\'m your draft'
  body    'Ready to send when you are.'
end
````

Ready to run

`bundle install`

`bundle exec ruby examble.rb`

Its nice to try an email with html and inline attachments as well.


Contributing
------------
All welcome. Please, Fork, extend, raise issues, Give feedback. (Its my first gem)..


Future plans
------------
- OAuth integration.  


See Also
--------
- [link Mail gem](https://github.com/mikel/mail)
- [link API specs](https://developers.google.com/google-apps/email-migration/)


Thanks To
---------
- [link mail-single_file_delivery](https://github.com/lsiden/mail-single_file_delivery (Partially used as a template ) (Partially used as a template )
- [link gdata library](http://code.google.com/p/gdata-ruby-util/ (Dependency used for communication with the Google Apps API)

Support
-------
Via GitHub. For inquiries about integration work contact me on timo@ewaza.nl


License
-------

(The MIT License)

Copyright (c) 2009, 2010, 2011, 2012

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.