Class: Mailchimp::Helper

Inherits:

Object

Object
Mailchimp::Helper

show all

Defined in:: lib/mailchimp/api.rb

Instance Attribute Summary collapse

#master ⇒ Object
Returns the value of attribute master.

Instance Method Summary collapse

#account_details(exclude = []) ⇒ Hash
Retrieve lots of account information including payments made, plan info, some account stats, installed modules, contact info, and more.
#campaigns_for_email(email, options = nil) ⇒ Array
Retrieve minimal data for all Campaigns a member was sent.
#chimp_chatter ⇒ Array
Return the current Chimp Chatter messages for an account.
#generate_text(type, content) ⇒ Hash
Have HTML content auto-converted to a text-only format.
#initialize(master) ⇒ Helper constructor
A new instance of Helper.
#inline_css(html, strip_css = false) ⇒ Hash
Send your HTML content to have the CSS inlined and optionally remove the original styles.
#lists_for_email(email) ⇒ Array
Retrieve minimal List data for all lists a member is subscribed to.
#ping ⇒ Hash
"Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything is good.
#search_campaigns(query, offset = 0, snip_start = nil, snip_end = nil) ⇒ Hash
Search all campaigns for the specified query terms.
#search_members(query, id = nil, offset = 0) ⇒ Hash
Search account wide or on a specific list using the specified query terms.
#verified_domains ⇒ Array
Retrieve all domain verification records for an account.

Constructor Details

#initialize(master) ⇒ `Helper`

Returns a new instance of Helper.



248
249
250

# File 'lib/mailchimp/api.rb', line 248

def initialize(master)
    @master = master
end

Instance Attribute Details

#master ⇒ `Object`

Returns the value of attribute master.



246
247
248

# File 'lib/mailchimp/api.rb', line 246

def master
  @master
end

Instance Method Details

#account_details(exclude = []) ⇒ `Hash`

Retrieve lots of account information including payments made, plan info, some account stats, installed modules, contact info, and more. No private information like Credit Card numbers is available.

Parameters:

exclude (Array) (defaults to: []) —
defaults to nothing for backwards compatibility. Allows controlling which extra arrays are returned since they can slow down calls. Valid keys are "modules", "orders", "rewards-credits", "rewards-inspections", "rewards-referrals", "rewards-applied", "integrations". Hint: "rewards-referrals" is typically the culprit. To avoid confusion, if data is excluded, the corresponding key will not be returned at all.

Returns:

(Hash) —
containing the details for the account tied to this API Key
- [String] username The company name associated with the account
- [String] user_id The Account user unique id (for building some links)
- [Bool] is_trial Whether the Account is in Trial mode (can only send campaigns to less than 100 emails)
- [Bool] is_approved Whether the Account has been approved for purchases
- [Bool] has_activated Whether the Account has been activated
- [String] timezone The timezone for the Account - default is "US/Eastern"
- [String] plan_type Plan Type - "monthly", "payasyougo", or "free"
- [Int] plan_low only for Monthly plans - the lower tier for list size
- [Int] plan_high only for Monthly plans - the upper tier for list size
- [String] plan_start_date only for Monthly plans - the start date for a monthly plan
- [Int] emails_left only for Free and Pay-as-you-go plans emails credits left for the account
- [Bool] pending_monthly Whether the account is finishing Pay As You Go credits before switching to a Monthly plan
- [String] first_payment date of first payment
- [String] last_payment date of most recent payment
- [Int] times_logged_in total number of times the account has been logged into via the web
- [String] last_login date/time of last login via the web
- [String] affiliate_link Monkey Rewards link for our Affiliate program
- [String] industry the user's selected industry
- [Hash] contact Contact details for the account
  - [String] fname First Name
  - [String] lname Last Name
  - [String] email Email Address
  - [String] company Company Name
  - [String] address1 Address Line 1
  - [String] address2 Address Line 2
  - [String] city City
  - [String] state State or Province
  - [String] zip Zip or Postal Code
  - [String] country Country name
  - [String] url Website URL
  - [String] phone Phone number
  - [String] fax Fax number
- [Array] modules a struct for each addon module installed in the account
  - [String] id An internal module id
  - [String] name The module name
  - [String] added The date the module was added
  - [Hash] data Any extra data associated with this module as key=>value pairs
- [Array] orders a struct for each order for the account
  - [Int] order_id The order id
  - [String] type The order type - either "monthly" or "credits"
  - [Double] amount The order amount
  - [String] date The order date
  - [Double] credits_used The total credits used
- [Hash] rewards Rewards details for the account including credits & inspections earned, number of referrals, referral details, and rewards used
  - [Int] referrals_this_month the total number of referrals this month
  - [String] notify_on whether or not we notify the user when rewards are earned
  - [String] notify_email the email address address used for rewards notifications
  - [Hash] credits Email credits earned:
    - [Int] this_month credits earned this month
    - [Int] total_earned credits earned all time
    - [Int] remaining credits remaining
  - [Hash] inspections Inbox Inspections earned:
    - [Int] this_month credits earned this month
    - [Int] total_earned credits earned all time
    - [Int] remaining credits remaining
  - [Array] referrals a struct for each referral, including:
    - [String] name the name of the account
    - [String] email the email address associated with the account
    - [String] signup_date the signup date for the account
    - [String] type the source for the referral
  - [Array] applied a struct for each applied rewards, including:
    - [Int] value the number of credits user
    - [String] date the date applied
    - [Int] order_id the order number credits were applied to
    - [String] order_desc the order description
- [Array] integrations a struct for each connected integrations that can be used with campaigns, including:
  - [Int] id an internal id for the integration
  - [String] name the integration name
  - [String] list_id either "any" when globally accessible or the list id it's valid for use against
  - [String] user_id if applicable, the user id for the integrated system
  - [String] account if applicable, the user/account name for the integrated system
  - [Array] profiles For Facebook, users/page that can be posted to.
    - [String] id the user or page id
    - [String] name the user or page name
    - [Bool] is_page whether this is a user or a page

# File 'lib/mailchimp/api.rb', line 330

def account_details(exclude=[])
    _params = {:exclude => exclude}
    return @master.call 'helper/account-details', _params
end

#campaigns_for_email(email, options = nil) ⇒ `Array`

Retrieve minimal data for all Campaigns a member was sent

Parameters:

email (Hash) —
a struct with one fo the following keys - failing to provide anything will produce an error relating to the email address
- [String] email an email address
- [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
- [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
options (Hash) (defaults to: nil) —
optional extra options to modify the returned data.
- [String] list_id optional A list_id to limit the campaigns to

Returns:

(Array) —
an array of structs containing campaign data for each matching campaign (ordered by send time ascending), including:
- [String] id the campaign unique id
- [String] title the campaign's title
- [String] subject the campaign's subject
- [String] send_time the time the campaign was sent
- [String] type the campaign type

# File 'lib/mailchimp/api.rb', line 348

def campaigns_for_email(email, options=nil)
    _params = {:email => email, :options => options}
    return @master.call 'helper/campaigns-for-email', _params
end

#chimp_chatter ⇒ `Array`

Return the current Chimp Chatter messages for an account.

Returns:

(Array) —
An array of structs containing data for each chatter message
- [String] message The chatter message
- [String] type The type of the message - one of lists:new-subscriber, lists:unsubscribes, lists:profile-updates, campaigns:facebook-likes, campaigns:facebook-comments, campaigns:forward-to-friend, lists:imports, or campaigns:inbox-inspections
- [String] url a url into the web app that the message could link to, if applicable
- [String] list_id the list_id a message relates to, if applicable. Deleted lists will return -DELETED-
- [String] campaign_id the list_id a message relates to, if applicable. Deleted campaigns will return -DELETED-
- [String] update_time The date/time the message was last updated

# File 'lib/mailchimp/api.rb', line 361

def chimp_chatter()
    _params = {}
    return @master.call 'helper/chimp-chatter', _params
end

#generate_text(type, content) ⇒ `Hash`

Have HTML content auto-converted to a text-only format. You can send: plain HTML, an existing Campaign Id, or an existing Template Id. Note that this will not save anything to or update any of your lists, campaigns, or templates. It's also not just Lynx and is very fine tuned for our template layouts - your mileage may vary.

Parameters:

type (String) —
The type of content to parse. Must be one of: "html", "url", "cid" (Campaign Id), "user_template_id", "base_template_id", "gallery_template_id"
content (Hash) —
The content to use. The key names should be the same as type and while listed as optional, may cause errors if the content is obviously required (ie, html)
- [String] html optional a single string value,
- [String] cid a valid Campaign Id
- [String] user_template_id the id of a user template
- [String] base_template_id the id of a built in base/basic template
- [String] gallery_template_id the id of a built in gallery template
- [String] url a valid & public URL to pull html content from

Returns:

(Hash) —
the content pass in converted to text.
- [String] text the converted html

# File 'lib/mailchimp/api.rb', line 377

def generate_text(type, content)
    _params = {:type => type, :content => content}
    return @master.call 'helper/generate-text', _params
end

#inline_css(html, strip_css = false) ⇒ `Hash`

Send your HTML content to have the CSS inlined and optionally remove the original styles.

Parameters:

html (String) —
Your HTML content
strip_css (Bool) (defaults to: false) —
optional Whether you want the CSS <style> tags stripped from the returned document. Defaults to false.

Returns:

(Hash) —
with a "html" key
- [String] html Your HTML content with all CSS inlined, just like if we sent it.

# File 'lib/mailchimp/api.rb', line 387

def inline_css(html, strip_css=false)
    _params = {:html => html, :strip_css => strip_css}
    return @master.call 'helper/inline-css', _params
end

#lists_for_email(email) ⇒ `Array`

Retrieve minimal List data for all lists a member is subscribed to.

Parameters:

email (Hash) —
a struct with one fo the following keys - failing to provide anything will produce an error relating to the email address
- [String] email an email address
- [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
- [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes

Returns:

(Array) —
An array of structs with info on the list_id the member is subscribed to.
- [String] id the list unique id
- [Int] web_id the id referenced in web interface urls
- [String] name the list name

# File 'lib/mailchimp/api.rb', line 401

def lists_for_email(email)
    _params = {:email => email}
    return @master.call 'helper/lists-for-email', _params
end

#ping ⇒ `Hash`

"Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything is good. Note than unlike most all of our methods, we don't throw an Exception if we are having issues. You will simply receive a different string back that will explain our view on what is going on.

Returns:

(Hash) —
a with a "msg" key
- [String] msg containing "Everything's Chimpy!" if everything is chimpy, otherwise returns an error message

# File 'lib/mailchimp/api.rb', line 409

def ping()
    _params = {}
    return @master.call 'helper/ping', _params
end

#search_campaigns(query, offset = 0, snip_start = nil, snip_end = nil) ⇒ `Hash`

Search all campaigns for the specified query terms

Parameters:

query (String) —
terms to search on
offset (Int) (defaults to: 0) —
optional the paging offset to use if more than 100 records match
snip_start (String) (defaults to: nil) —
optional by default clear text is returned. To have the match highlighted with something (like a strong HTML tag), both this and "snip_end" must be passed. You're on your own to not break the tags - 25 character max.
snip_end (String) (defaults to: nil) —
optional see "snip_start" above.

Returns:

(Hash) —
containing the total matches and current results
- [Int] total total campaigns matching
- [Array] results matching campaigns and snippets
- [String] snippet the matching snippet for the campaign
- [Hash] campaign the matching campaign's details - will return same data as single campaign from campaigns/list()

# File 'lib/mailchimp/api.rb', line 424

def search_campaigns(query, offset=0, snip_start=nil, snip_end=nil)
    _params = {:query => query, :offset => offset, :snip_start => snip_start, :snip_end => snip_end}
    return @master.call 'helper/search-campaigns', _params
end

#search_members(query, id = nil, offset = 0) ⇒ `Hash`

Search account wide or on a specific list using the specified query terms

Parameters:

query (String) —
terms to search on, just like you do in the app
id (String) (defaults to: nil) —
optional the list id to limit the search to. Get by calling lists/list()
offset (Int) (defaults to: 0) —
optional the paging offset to use if more than 100 records match

Returns:

(Hash) —
An array of both exact matches and partial matches over a full search
- [Hash] exact_matches containing the exact email address matches and current results
  - [Int] total total members matching
  - [Array] members each entry will be struct matching the data format for a single member as returned by lists/member-info()
- [Hash] full_search containing the total matches and current results
  - [Int] total total members matching
  - [Array] members each entry will be struct matching the data format for a single member as returned by lists/member-info()

# File 'lib/mailchimp/api.rb', line 440

def search_members(query, id=nil, offset=0)
    _params = {:query => query, :id => id, :offset => offset}
    return @master.call 'helper/search-members', _params
end

#verified_domains ⇒ `Array`

Retrieve all domain verification records for an account

Returns:

(Array) —
structs for each domain verification has been attempted for
- [String] domain the verified domain
- [String] status the status of the verification - either "verified" or "pending"
- [String] email the email address used for verification - "pre-existing" if we automatically backfilled it at some point

# File 'lib/mailchimp/api.rb', line 450

def verified_domains()
    _params = {}
    return @master.call 'helper/verified-domains', _params
end

Class: Mailchimp::Helper

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(master) ⇒ Helper

Instance Attribute Details

#master ⇒ Object

Instance Method Details

#account_details(exclude = []) ⇒ Hash

#campaigns_for_email(email, options = nil) ⇒ Array

#chimp_chatter ⇒ Array

#generate_text(type, content) ⇒ Hash

#inline_css(html, strip_css = false) ⇒ Hash

#lists_for_email(email) ⇒ Array

#ping ⇒ Hash

#search_campaigns(query, offset = 0, snip_start = nil, snip_end = nil) ⇒ Hash

#search_members(query, id = nil, offset = 0) ⇒ Hash

#verified_domains ⇒ Array

#initialize(master) ⇒ `Helper`

#master ⇒ `Object`

#account_details(exclude = []) ⇒ `Hash`

#campaigns_for_email(email, options = nil) ⇒ `Array`

#chimp_chatter ⇒ `Array`

#generate_text(type, content) ⇒ `Hash`

#inline_css(html, strip_css = false) ⇒ `Hash`

#lists_for_email(email) ⇒ `Array`

#ping ⇒ `Hash`

#search_campaigns(query, offset = 0, snip_start = nil, snip_end = nil) ⇒ `Hash`

#search_members(query, id = nil, offset = 0) ⇒ `Hash`

#verified_domains ⇒ `Array`