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:



48
49
50
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
 
# File 'lib/mailup.rb', line 48

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

  # 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.



22
23
24
 
# File 'lib/mailup.rb', line 22

def access_token
  @access_token
end

#debug ⇒ Object

Returns the value of attribute debug.



22
23
24
 
# File 'lib/mailup.rb', line 22

def debug
  @debug
end

#host ⇒ Object

Returns the value of attribute host.



22
23
24
 
# File 'lib/mailup.rb', line 22

def host
  @host
end

#path ⇒ Object

Returns the value of attribute path.



22
23
24
 
# File 'lib/mailup.rb', line 22

def path
  @path
end

Instance Method Details

#console ⇒ Object

Access the console API methods

Examples:


lists = mailup.console.user.lists


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

def console
  Console::Base.new self
end

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

Make a DELETE request with the Access Token

See Also:



137
138
139
 
# File 'lib/mailup.rb', line 137

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:



109
110
111
 
# File 'lib/mailup.rb', line 109

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

#handle_response(response) ⇒ Object

Handle the response of a request



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/mailup.rb', line 142

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



167
168
169
170
171
172
173
 
# File 'lib/mailup.rb', line 167

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:



130
131
132
 
# File 'lib/mailup.rb', line 130

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:



116
117
118
 
# File 'lib/mailup.rb', line 116

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

#public ⇒ Object

Access the public API methods

Examples:


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


191
192
193
 
# File 'lib/mailup.rb', line 191

def public
  Public::Base.new self
end

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

Make a PUT request with the Access Token

See Also:



123
124
125
 
# File 'lib/mailup.rb', line 123

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



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/mailup.rb', line 90

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)


201
202
203
 
# File 'lib/mailup.rb', line 201

def stats
  Stats::Base.new self
end