Class: MailUp::API

Inherits:
Object
  • Object
show all
Defined in:
lib/mailup.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(credentials = nil, debug = false) ⇒ API

Initialize a new (thread-safe) API instance.

Examples:


credentials = {
  client_id: "1324567890",
  client_secret: "123abc456def",
  oauth: {
    token: "1324567890",
    refresh_token: "1324567890",
    expires_at: 123456789,
  }
}
mailup = MailUp::API.new(credentials)

Parameters:

  • credentials (Hash) (defaults to: nil) —

    for connecting to the MailUp API.

    • client_id [String]

    • client_secret [String]

    • oauth [Hash]

      • token [String]

      • refresh_token [String]

      • expires_at [Integer]

  • debug (Boolean) (defaults to: false) —

    whether or not to raise errors.

Raises:



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/mailup.rb', line 51

def initialize(credentials=nil, debug=false)
  @debug = debug
  @host = 'https://services.mailup.com'
  @path = ''
  @credentials = credentials

  # Validate the credentials
  raise Error.new, 'MailUp credentials missing' if credentials.nil? or !credentials.is_a?(Hash)
  [:client_id, :client_secret, :oauth].each do |key|
    raise Error.new, "MailUp credentials must include a #{key.to_s} key" unless credentials.has_key?(key)
  end
  raise Error.new, 'MailUp credentials :oauth must be a hash' unless credentials[:oauth].is_a?(Hash)
  [:token, :refresh_token, :expires_at].each do |key|
    raise Error.new, "MailUp credentials :oauth hash must include a #{key.to_s} key" unless credentials[:oauth].has_key?(key)
  end

  # Create a OAuth2 client instance
  client = OAuth2::Client.new(
    credentials[:client_id],
    credentials[:client_secret],
    site: @host,
    authorize_url: "/Authorization/OAuth/LogOn",
    token_url: "/Authorization/OAuth/Token",
    raise_errors: @debug
  )

  # Create an access_token instance
  @access_token = OAuth2::AccessToken.new(
    client,
    credentials[:oauth][:token],
    {
      refresh_token: credentials[:oauth][:refresh_token],
      expires_at: credentials[:oauth][:expires_at]
    }
  )
end

Instance Attribute Details

#access_token ⇒ Object

Returns the value of attribute access_token.



25
26
27
 
# File 'lib/mailup.rb', line 25

def access_token
  @access_token
end

#credentials ⇒ Object

Returns the value of attribute credentials.



25
26
27
 
# File 'lib/mailup.rb', line 25

def credentials
  @credentials
end

#debug ⇒ Object

Returns the value of attribute debug.



25
26
27
 
# File 'lib/mailup.rb', line 25

def debug
  @debug
end

#host ⇒ Object

Returns the value of attribute host.



25
26
27
 
# File 'lib/mailup.rb', line 25

def host
  @host
end

#path ⇒ Object

Returns the value of attribute path.



25
26
27
 
# File 'lib/mailup.rb', line 25

def path
  @path
end

Instance Method Details

#console ⇒ Object

Access the console API methods

Examples:


lists = mailup.console.user.lists


204
205
206
 
# File 'lib/mailup.rb', line 204

def console
  Console::Base.new self
end

#delete(path, opts = {}, &block) ⇒ Object

Make a DELETE request with the Access Token

See Also:



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

def delete(path, opts={}, &block) # :nodoc:
  request(:delete, path, opts, &block)
end

#get(path, opts = {}, &block) ⇒ Object

Make a GET request with the Access Token

See Also:



132
133
134
 
# File 'lib/mailup.rb', line 132

def get(path, opts={}, &block) # :nodoc:
  request(:get, path, opts, &block)
end

#handle_response(response) ⇒ Object

Handle the response of a request



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/mailup.rb', line 165

def handle_response(response) # :nodoc:
  case response.status
  when 400
    raise BadRequest.new response.parsed
  when 401
    raise Unauthorized.new
  when 404
    raise NotFound.new
  when 400...500
    raise ClientError.new response.parsed
  when 500...600
    raise ServerError.new
  else
    case response.body
    when ''
      true
    when is_a?(Integer)
      response.body
    else
      response.parsed
    end
  end
end

#headers ⇒ Object

Set the request headers



190
191
192
193
194
195
196
 
# File 'lib/mailup.rb', line 190

def headers # :nodoc:
  {
    'User-Agent' => "mailup-ruby-#{VERSION}",
    'Content-Type' => 'application/json; charset=utf-8',
    'Accept' => 'application/json'
  }
end

#patch(path, opts = {}, &block) ⇒ Object

Make a PATCH request with the Access Token

See Also:



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

def patch(path, opts={}, &block) # :nodoc:
  request(:patch, path, opts, &block)
end

#post(path, opts = {}, &block) ⇒ Object

Make a POST request with the Access Token

See Also:



139
140
141
 
# File 'lib/mailup.rb', line 139

def post(path, opts={}, &block) # :nodoc:
  request(:post, path, opts, &block)
end

#provisioning_request(path, body = nil) ⇒ Object

Make a request with for Provisioning Calls.

Parameters:

  • verb (Symbol) —

    the HTTP request method

  • path (String) —

    the HTTP URL path of the request

  • opts (Hash) —

    the options to make the request with



116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/mailup.rb', line 116

def provisioning_request(path, body = nil) # :nodoc:
  uri = URI.parse(@host)
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  req = Net::HTTP::Post.new(path, initheader = {'Content-Type' =>'application/json'})
  req.basic_auth @credentials[:client_id], @credentials[:client_secret]
  req.body = body.to_json

  http.request(req).body.to_json
end

#public ⇒ Object

Access the public API methods

Examples:


activation = mailup.public.activation.new(...)


214
215
216
 
# File 'lib/mailup.rb', line 214

def public
  Public::Base.new self
end

#put(path, opts = {}, &block) ⇒ Object

Make a PUT request with the Access Token

See Also:



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

def put(path, opts={}, &block) # :nodoc:
  request(:put, path, opts, &block)
end

#request(method, path, opts = {}, &block) ⇒ Object

Make a request with the Access Token.

Parameters:

  • verb (Symbol) —

    the HTTP request method

  • path (String) —

    the HTTP URL path of the request

  • opts (Hash) (defaults to: {}) —

    the options to make the request with



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

def request(method, path, opts={}, &block) # :nodoc:
  unless @access_token == nil
    # Refresh token if needed
    @access_token = @access_token.refresh! if @access_token.expired?
    # Ensure the body is JSON
    opts[:body] = MultiJson.dump(opts[:body]) if opts[:body]
    # Set the headers
    opts[:headers] ||= {}
    opts[:headers].merge!(headers)
    # Make the request
    req = @access_token.send(method, path, opts)
    # Handle the response
    handle_response(req)
  end
end

#stats ⇒ Object

Access the email statistics API methods

Examples:


views = mailup.stats.message.views_count(1)


224
225
226
 
# File 'lib/mailup.rb', line 224

def stats
  Stats::Base.new self
end