Uakari is a simple API wrapper for the MailChimp STS API 1.0, which wraps Amazon SES.
##Installation
$ gem install uakari
##Requirements
A paid MailChimp account, MailChimp API key, and Amazon AWS account with SES ready to go. You can see your API keys here. Caveats include the inability to send to unconfirmed email addresses until you request (and Amazon provides) production access to your AWS account.
##Usage
There are a few ways to use Uakari.
You can create an instance of the API wrapper:
u = Uakari.new("your_api_key")
You can set your api_key globally and call class methods:
Uakari.api_key = "your_api_key"
Uakari.send_email(...)
You can also set the environment variable 'MC_API_KEY' and Uakari will use it when you create an instance:
u = Uakari.new
Send a message so a single email:
response = u.send_email({
:track_opens => true,
:track_clicks => true,
:tags => ["awesome", "tags", "here"] #optional STS tags
:message => {
:subject => 'your subject',
:html => '<html>hello world</html>',
:text => 'hello world',
:from_name => 'John Smith',
:from_email => '[email protected]',
:to_email => ['[email protected]']
}
})
Calling other methods is as simple as calling API methods directly on the Uakari instance (e.g. u.get_send_quota, u.verify_email_address, and so on). Check the API documentation for more information about API calls and their parameters.
You can tell ActionMailer to send mail using Mailchimp STS by adding the follow to to your config/application.rb or to the proper environment (eg. config/production.rb) :
config.action_mailer.delivery_method = :uakari
config.action_mailer.uakari_settings = {
:api_key => "your_mailchimp_apikey",
:track_clicks => true,
:track_opens => true,
:from_name => "Change Me"
:tags => ["awesome", "tags", "here"] #optional STS tags
}
These setting will allow you to use ActionMailer as you normally would, any calls to mail() will be sent using Mailchimp STS
If you want to use ActionMailer and change your tags dynamically at runtime, you can do something like:
ActionMailer::Base.uakari_settings[:tags] = ["dynamically", "set", "tags"]
You can also set tags on individual pieces of mail by using Mail unstructured fields. Multiple tags may be set, but they cannot be set with an array, so set them individually:
> mail = ExampleMailer.hello_email(. . .)
> mail[:tags] = 'example'
> mail[:tags]
=> example # it's a single Mail::Field object
> mail[:tags] = 'hello'
> mail[:tags]
=> [example, hello] # it's an Array of Mail::Field objects
Don't do this, Mail will try to make a single field out of the entire array:
> mail[:tags] = ['this', 'will', 'break']
> mail[:tags]
(Object doesn't support #inspect)
> mail.deliver
NoMethodError: undefined method `encoding' for ["howdy", "doody"]:Array # told you so...
Uakari defaults to a 30 second timeout. You can optionally set your own timeout (in seconds) like so:
u.timeout = 5
##Thanks
- Stafford Brooke
- Loren Norman
- Ali Faiz
- Calvin Yu
- James Kyburz
- Scott Simon
- Rails for camelize gsub
##Copyrights
- Copyright (c) 2010 Amro Mousa. See LICENSE.txt for details.
- MailChimp (c) 2001-2011 The Rocket Science Group.
- Amazon SES (c) 2011 Amazon