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.



250
251
252

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

def initialize(master)
    @master = master
end

Instance Attribute Details

#master ⇒ `Object`

Returns the value of attribute master.



248
249
250

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

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 Account username
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 332

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 350

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 363

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 379

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 389

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
- Web_id
  
  the id referenced in web interface urls
- Name
  
  the list name

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

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 411

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()
- Hash
  
  summary if available, the matching campaign’s report/summary data, other wise empty

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

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, <a href=“kb.mailchimp.com/article/i-cant-find-a-recipient-on-my-list” target=“_blank”>just like you do in the app</a>
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 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()
- 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 443

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 453

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`