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.



110
111
112
113
114
 
# File 'lib/createsend/createsend.rb', line 110

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.



51
52
53
 
# File 'lib/createsend/createsend.rb', line 51

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.



68
69
70
71
72
73
74
 
# File 'lib/createsend/createsend.rb', line 68

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.



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

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.



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

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.



62
63
64
 
# File 'lib/createsend/createsend.rb', line 62

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 



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

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.



177
178
179
180
 
# File 'lib/createsend/createsend.rb', line 177

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.



126
127
128
 
# File 'lib/createsend/createsend.rb', line 126

def auth(auth_details)
  @auth_details = auth_details
end

#billing_details ⇒ Object

Get your billing details.



153
154
155
156
 
# File 'lib/createsend/createsend.rb', line 153

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

#clients ⇒ Object

Gets your clients.



147
148
149
150
 
# File 'lib/createsend/createsend.rb', line 147

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

#countries ⇒ Object

Gets valid countries.



159
160
161
162
 
# File 'lib/createsend/createsend.rb', line 159

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

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



240
241
242
243
 
# File 'lib/createsend/createsend.rb', line 240

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.



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

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 



222
223
224
225
 
# File 'lib/createsend/createsend.rb', line 222

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.



183
184
185
186
 
# File 'lib/createsend/createsend.rb', line 183

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

#handle_response(response) ⇒ Object

:nodoc:



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

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 429
    raise TooManyRequests.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 



228
229
230
231
 
# File 'lib/createsend/createsend.rb', line 228

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

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



234
235
236
237
 
# File 'lib/createsend/createsend.rb', line 234

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.



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

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.



189
190
191
192
193
 
# File 'lib/createsend/createsend.rb', line 189

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.



165
166
167
168
 
# File 'lib/createsend/createsend.rb', line 165

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

#timezones ⇒ Object

Gets valid timezones.



171
172
173
174
 
# File 'lib/createsend/createsend.rb', line 171

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