Class: CreateSend::CreateSend

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/createsend/createsend.rb

Overview

Provides high level CreateSend functionality/data you’ll probably need.

Constant Summary collapse

@@base_uri = 
"https://api.createsend.com/api/v3.3"
@@oauth_base_uri = 
"https://api.createsend.com/oauth"
@@oauth_token_uri = 
"#{@@oauth_base_uri}/token"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ CreateSend

Returns a new instance of CreateSend.



108
109
110
111
112
 
# File 'lib/createsend/createsend.rb', line 108

def initialize(*args)
  if args.size > 0
    auth args.first # Expect auth details as first argument
  end
end

Instance Attribute Details

#auth_details ⇒ Object (readonly)

Returns the value of attribute auth_details.



49
50
51
 
# File 'lib/createsend/createsend.rb', line 49

def auth_details
  @auth_details
end

Class Method Details

.authorize_url(client_id, redirect_uri, scope, state = nil) ⇒ Object

Get the authorization URL for your application, given the application’s client_id, redirect_uri, scope, and optional state data.



66
67
68
69
70
71
72
 
# File 'lib/createsend/createsend.rb', line 66

def self.authorize_url(client_id, redirect_uri, scope, state=nil)
  qs = "client_id=#{CGI.escape(client_id.to_s)}"
  qs << "&redirect_uri=#{CGI.escape(redirect_uri.to_s)}"
  qs << "&scope=#{CGI.escape(scope.to_s)}"
  qs << "&state=#{CGI.escape(state.to_s)}" if state
  "#{@@oauth_base_uri}?#{qs}"
end

.exchange_token(client_id, client_secret, redirect_uri, code) ⇒ Object

Exchange a provided OAuth code for an OAuth access token, ‘expires in’ value, and refresh token.



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/createsend/createsend.rb', line 76

def self.exchange_token(client_id, client_secret, redirect_uri, code)
  body = "grant_type=authorization_code"
  body << "&client_id=#{CGI.escape(client_id.to_s)}"
  body << "&client_secret=#{CGI.escape(client_secret.to_s)}"
  body << "&redirect_uri=#{CGI.escape(redirect_uri.to_s)}"
  body << "&code=#{CGI.escape(code.to_s)}"
  options = {:body => body}
  response = HTTParty.post(@@oauth_token_uri, options)
  if response.has_key? 'error' and response.has_key? 'error_description'
    err = "Error exchanging code for access token: "
    err << "#{response['error']} - #{response['error_description']}"
    raise err
  end
  r = Hashie::Mash.new(response)
  [r.access_token, r.expires_in, r.refresh_token]
end

.refresh_access_token(refresh_token) ⇒ Object

Refresh an OAuth access token, given an OAuth refresh token. Returns a new access token, ‘expires in’ value, and refresh token.



95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/createsend/createsend.rb', line 95

def self.refresh_access_token(refresh_token)
  options = {
    :body => "grant_type=refresh_token&refresh_token=#{CGI.escape(refresh_token)}" }
  response = HTTParty.post(@@oauth_token_uri, options)
  if response.has_key? 'error' and response.has_key? 'error_description'
    err = "Error refreshing access token: "
    err << "#{response['error']} - #{response['error_description']}"
    raise err
  end
  r = Hashie::Mash.new(response)
  [r.access_token, r.expires_in, r.refresh_token]
end

.user_agent(user_agent) ⇒ Object

Set a custom user agent string to be used when instances of CreateSend::CreateSend make API calls.

user_agent - The user agent string to use in the User-Agent header when

instances of this class make API calls. If set to nil, the
default value of CreateSend::USER_AGENT_STRING will be used.



60
61
62
 
# File 'lib/createsend/createsend.rb', line 60

def self.user_agent(user_agent)
  headers({'User-Agent' => user_agent || USER_AGENT_STRING})
end

Instance Method Details

#add_auth_details_to_options(args) ⇒ Object 



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/createsend/createsend.rb', line 244

def add_auth_details_to_options(args)
  if @auth_details
    options = {}
    if args.size > 1
      options = args[1]
    end
    if @auth_details.has_key? :access_token
      options[:headers] = {
        "Authorization" => "Bearer #{@auth_details[:access_token]}" }
    elsif @auth_details.has_key? :api_key
      if not options.has_key? :basic_auth
        options[:basic_auth] = {
          :username => @auth_details[:api_key], :password => 'x' }
      end
    end
    args[1] = options
  end
  args
end

#administrators ⇒ Object

Gets the administrators for the account.



175
176
177
178
 
# File 'lib/createsend/createsend.rb', line 175

def administrators
  response = get('/admins.json')
  response.map{|item| Hashie::Mash.new(item)}
end

#auth(auth_details) ⇒ Object

Authenticate using either OAuth or an API key.



124
125
126
 
# File 'lib/createsend/createsend.rb', line 124

def auth(auth_details)
  @auth_details = auth_details
end

#billing_details ⇒ Object

Get your billing details.



151
152
153
154
 
# File 'lib/createsend/createsend.rb', line 151

def billing_details
  response = get('/billingdetails.json')
  Hashie::Mash.new(response)
end

#clients ⇒ Object

Gets your clients.



145
146
147
148
 
# File 'lib/createsend/createsend.rb', line 145

def clients
  response = get('/clients.json')
  response.map{|item| Hashie::Mash.new(item)}
end

#countries ⇒ Object

Gets valid countries.



157
158
159
160
 
# File 'lib/createsend/createsend.rb', line 157

def countries
  response = get('/countries.json')
  response.parsed_response
end

#delete(*args) ⇒ Object Also known as: cs_delete 



238
239
240
241
 
# File 'lib/createsend/createsend.rb', line 238

def delete(*args)
  args = add_auth_details_to_options(args)
  handle_response CreateSend.delete(*args)
end

#external_session_url(email, chrome, url, integrator_id, client_id) ⇒ Object

Get a URL which initiates a new external session for the user with the given email. Full details: www.campaignmonitor.com/api/account/#single_sign_on

email - The email address of the Campaign Monitor user for whom

the login session should be created.

chrome - Which ‘chrome’ to display - Must be either “all”,

"tabs", or "none".

url - The URL to display once logged in. e.g. “/subscribers/” integrator_id - The integrator ID. You need to contact Campaign Monitor

support to get an integrator ID.

client_id - The Client ID of the client which should be active once

logged in to the Campaign Monitor account.

Returns An object containing a single field SessionUrl which represents the URL to initiate the external Campaign Monitor session.



209
210
211
212
213
214
215
216
217
218
 
# File 'lib/createsend/createsend.rb', line 209

def external_session_url(email, chrome, url, integrator_id, client_id)
  options = { :body => {
    :Email => email,
    :Chrome => chrome,
    :Url => url,
    :IntegratorID => integrator_id,
    :ClientID => client_id }.to_json }
  response = put("/externalsession.json", options)
  Hashie::Mash.new(response)
end

#get(*args) ⇒ Object Also known as: cs_get 



220
221
222
223
 
# File 'lib/createsend/createsend.rb', line 220

def get(*args)
  args = add_auth_details_to_options(args)
  handle_response CreateSend.get(*args)
end

#get_primary_contact ⇒ Object

Gets the primary contact for the account.



181
182
183
184
 
# File 'lib/createsend/createsend.rb', line 181

def get_primary_contact
  response = get('/primarycontact.json')
  Hashie::Mash.new(response)
end

#handle_response(response) ⇒ Object

:nodoc:



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/createsend/createsend.rb', line 264

def handle_response(response) # :nodoc:
  case response.code
  when 400
    raise BadRequest.new(Hashie::Mash.new response)
  when 401
    data = Hashie::Mash.new(response)
    case data.Code
    when 120
      raise InvalidOAuthToken.new data
    when 121
      raise ExpiredOAuthToken.new data
    when 122
      raise RevokedOAuthToken.new data
    else
      raise Unauthorized.new data
    end
  when 404
    raise NotFound.new
  when 400...500
    raise ClientError.new
  when 500...600
    raise ServerError.new
  else
    response
  end
end

#post(*args) ⇒ Object Also known as: cs_post 



226
227
228
229
 
# File 'lib/createsend/createsend.rb', line 226

def post(*args)
  args = add_auth_details_to_options(args)
  handle_response CreateSend.post(*args)
end

#put(*args) ⇒ Object Also known as: cs_put 



232
233
234
235
 
# File 'lib/createsend/createsend.rb', line 232

def put(*args)
  args = add_auth_details_to_options(args)
  handle_response CreateSend.put(*args)
end

#refresh_token ⇒ Object

Refresh the current OAuth token using the current refresh token.



129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/createsend/createsend.rb', line 129

def refresh_token
  if not @auth_details or
    not @auth_details.has_key? :refresh_token or
    not @auth_details[:refresh_token]
    raise '@auth_details[:refresh_token] does not contain a refresh token.'
  end

  access_token, expires_in, refresh_token =
    self.class.refresh_access_token @auth_details[:refresh_token]
  auth({
    :access_token => access_token,
    :refresh_token => refresh_token})
  [access_token, expires_in, refresh_token]
end

#set_primary_contact(email) ⇒ Object

Set the primary contect for the account.



187
188
189
190
191
 
# File 'lib/createsend/createsend.rb', line 187

def set_primary_contact(email)
  options = { :query => { :email => email } }
  response = put("/primarycontact.json", options)
  Hashie::Mash.new(response)
end

#systemdate ⇒ Object

Gets the current date in your account’s timezone.



163
164
165
166
 
# File 'lib/createsend/createsend.rb', line 163

def systemdate
  response = get('/systemdate.json')
  Hashie::Mash.new(response)
end

#timezones ⇒ Object

Gets valid timezones.



169
170
171
172
 
# File 'lib/createsend/createsend.rb', line 169

def timezones
  response = get('/timezones.json')
  response.parsed_response
end