Class: Mailgun::Client

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

Overview

A Mailgun::Client object is used to communicate with the Mailgun API. It is a wrapper around RestClient so you don’t have to worry about the HTTP aspect of communicating with our API.

See the Github documentation for full examples.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key = Mailgun.api_key, api_host = Mailgun.api_host || 'api.mailgun.net', api_version = Mailgun.api_version || 'v3', ssl = true, test_mode = false, timeout = nil, proxy_url = Mailgun.proxy_url) ⇒ Client

Returns a new instance of Client.



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/mailgun/client.rb', line 13

def initialize(api_key = Mailgun.api_key,
               api_host = Mailgun.api_host || 'api.mailgun.net',
               api_version = Mailgun.api_version  || 'v3',
               ssl = true,
               test_mode = false,
               timeout = nil,
               proxy_url = Mailgun.proxy_url)

  rest_client_params = {
    user: 'api',
    password: api_key,
    user_agent: "mailgun-sdk-ruby/#{Mailgun::VERSION}"
  }
  rest_client_params[:timeout] = timeout if timeout

  endpoint = endpoint_generator(api_host, api_version, ssl)
  RestClient.proxy = proxy_url
  @http_client = RestClient::Resource.new(endpoint, rest_client_params)
  @test_mode = test_mode
end

Class Method Details

.deliveries ⇒ Hash

Provides a store of all the emails sent in test mode so you can check them.

Returns:

  • (Hash) 


63
64
65
 
# File 'lib/mailgun/client.rb', line 63

def self.deliveries
  @@deliveries ||= []
end

Instance Method Details

#delete(resource_path) ⇒ Mailgun::Response

Generic Mailgun DELETE Handler

with. Be sure to include your domain, where necessary.

Parameters:

  • resource_path (String) —

    This is the API resource you wish to interact

Returns:



160
161
162
163
164
165
 
# File 'lib/mailgun/client.rb', line 160

def delete(resource_path)
  response = @http_client[resource_path].delete
  Response.new(response)
rescue => err
  raise communication_error err
end

#disable_test_mode! ⇒ Object

Disable test mode

Reverts the test_mode flag and allows the client to send messages.



44
45
46
 
# File 'lib/mailgun/client.rb', line 44

def disable_test_mode!
  @test_mode = false
end

#enable_test_mode! ⇒ Object

Enable test mode

Prevents sending of any messages.



37
38
39
 
# File 'lib/mailgun/client.rb', line 37

def enable_test_mode!
  @test_mode = true
end

#get(resource_path, params = nil, accept = '*/*') ⇒ Mailgun::Response

Generic Mailgun GET Handler

with. Be sure to include your domain, where necessary. containing required parameters for the requested resource.

Parameters:

  • resource_path (String) —

    This is the API resource you wish to interact

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

    This should be a standard Hash

  • accept (String) (defaults to: '*/*') —

    Acceptable Content-Type of the response body.

Returns:



130
131
132
133
134
135
136
137
138
139
 
# File 'lib/mailgun/client.rb', line 130

def get(resource_path, params = nil, accept = '*/*')
  if params
    response = @http_client[resource_path].get(params: params, accept: accept)
  else
    response = @http_client[resource_path].get(accept: accept)
  end
  Response.new(response)
rescue => err
  raise communication_error err
end

#post(resource_path, data, headers = {}) ⇒ Mailgun::Response

Generic Mailgun POST Handler

with. Be sure to include your domain, where necessary. containing required parameters for the requested resource.

Parameters:

  • resource_path (String) —

    This is the API resource you wish to interact

  • data (Hash) —

    This should be a standard Hash

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

    Additional headers to pass to the resource.

Returns:



115
116
117
118
119
120
 
# File 'lib/mailgun/client.rb', line 115

def post(resource_path, data, headers = {})
  response = @http_client[resource_path].post(data, headers)
  Response.new(response)
rescue => err
  raise communication_error err
end

#put(resource_path, data) ⇒ Mailgun::Response

Generic Mailgun PUT Handler

with. Be sure to include your domain, where necessary. containing required parameters for the requested resource.

Parameters:

  • resource_path (String) —

    This is the API resource you wish to interact

  • data (Hash) —

    This should be a standard Hash

Returns:



148
149
150
151
152
153
 
# File 'lib/mailgun/client.rb', line 148

def put(resource_path, data)
  response = @http_client[resource_path].put(data)
  Response.new(response)
rescue => err
  raise communication_error err
end

#send_message(working_domain, data) ⇒ Mailgun::Response

Simple Message Sending

containing required parameters for the requested resource.

Parameters:

  • working_domain (String) —

    This is the domain you wish to send from.

  • data (Hash) —

    This should be a standard Hash

Returns:



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/mailgun/client.rb', line 73

def send_message(working_domain, data)
  perform_data_validation(working_domain, data)

  if test_mode? then
    Mailgun::Client.deliveries << data
    return Response.from_hash(
      {
        :body => "{\"id\": \"test-mode-mail-#{SecureRandom.uuid}@localhost\", \"message\": \"Queued. Thank you.\"}",
        :code => 200,
      }
    )
  end

  case data
  when Hash
    # Remove nil values from the data hash
    # Submitting nils to the API will likely cause an error.
    #  See also: https://github.com/mailgun/mailgun-ruby/issues/32
    data = data.select { |k, v| v != nil }

    if data.key?(:message)
      if data[:message].is_a?(String)
        data[:message] = convert_string_to_file(data[:message])
      end
      return post("#{working_domain}/messages.mime", data)
    end
    post("#{working_domain}/messages", data)
  when MessageBuilder
    post("#{working_domain}/messages", data.message)
  else
    fail ParameterError.new('Unknown data type for data parameter.', data)
  end
end

#set_api_key(api_key) ⇒ Object

Change API key



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

def set_api_key(api_key)
  @http_client.options[:password] = api_key
end

#suppressions(domain) ⇒ Mailgun::Suppressions

Constructs a Suppressions client for the given domain.

Parameters:

  • domain (String) —

    Domain which suppressions requests will be made for

Returns:



171
172
173
 
# File 'lib/mailgun/client.rb', line 171

def suppressions(domain)
  Suppressions.new(self, domain)
end

#test_mode? ⇒ Boolean

Client is in test mode?

Returns:

  • (Boolean) —

    Is the client set in test mode?



56
57
58
 
# File 'lib/mailgun/client.rb', line 56

def test_mode?
  @test_mode
end