class Mailgun::Client

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.

Public Class Methods

deliveries() click to toggle source

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

@return [Hash]

# File lib/mailgun/client.rb, line 58
def self.deliveries
  @@deliveries ||= []
end
new(api_key = Mailgun.api_key, api_host = 'api.mailgun.net', api_version = 'v3', ssl = true, test_mode = false, timeout = nil, proxy_url = nil) click to toggle source
# File lib/mailgun/client.rb, line 13
def initialize(api_key = Mailgun.api_key,
               api_host = 'api.mailgun.net',
               api_version = 'v3',
               ssl = true,
               test_mode = false,
               timeout = nil,
               proxy_url = nil)

  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

Public Instance Methods

delete(resource_path) click to toggle source

Generic Mailgun DELETE Handler

@param [String] resource_path This is the API resource you wish to interact with. Be sure to include your domain, where necessary. @return [Mailgun::Response] A Mailgun::Response object.

# File lib/mailgun/client.rb, line 155
def delete(resource_path)
  response = @http_client[resource_path].delete
  Response.new(response)
rescue => err
  raise communication_error err
end
disable_test_mode!() click to toggle source

Disable test mode

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

# File lib/mailgun/client.rb, line 44
def disable_test_mode!
  @test_mode = false
end
enable_test_mode!() click to toggle source

Enable test mode

Prevents sending of any messages.

# File lib/mailgun/client.rb, line 37
def enable_test_mode!
  @test_mode = true
end
get(resource_path, params = nil, accept = '*/*') click to toggle source

Generic Mailgun GET Handler

@param [String] resource_path This is the API resource you wish to interact with. Be sure to include your domain, where necessary. @param [Hash] params This should be a standard Hash containing required parameters for the requested resource. @param [String] accept Acceptable Content-Type of the response body. @return [Mailgun::Response] A Mailgun::Response object.

# File lib/mailgun/client.rb, line 125
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 = {}) click to toggle source

Generic Mailgun POST Handler

@param [String] resource_path This is the API resource you wish to interact with. Be sure to include your domain, where necessary. @param [Hash] data This should be a standard Hash containing required parameters for the requested resource. @param [Hash] headers Additional headers to pass to the resource. @return [Mailgun::Response] A Mailgun::Response object.

# File lib/mailgun/client.rb, line 110
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) click to toggle source

Generic Mailgun PUT Handler

@param [String] resource_path This is the API resource you wish to interact with. Be sure to include your domain, where necessary. @param [Hash] data This should be a standard Hash containing required parameters for the requested resource. @return [Mailgun::Response] A Mailgun::Response object.

# File lib/mailgun/client.rb, line 143
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) click to toggle source

Simple Message Sending

@param [String] working_domain This is the domain you wish to send from. @param [Hash] data This should be a standard Hash containing required parameters for the requested resource. @return [Mailgun::Response] A Mailgun::Response object.

# File lib/mailgun/client.rb, line 68
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
suppressions(domain) click to toggle source

Constructs a Suppressions client for the given domain.

@param [String] domain Domain which suppressions requests will be made for @return [Mailgun::Suppressions]

# File lib/mailgun/client.rb, line 166
def suppressions(domain)
  Suppressions.new(self, domain)
end
test_mode?() click to toggle source

Client is in test mode?

@return [Boolean] Is the client set in test mode?

# File lib/mailgun/client.rb, line 51
def test_mode?
  @test_mode
end

Private Instance Methods

communication_error(e) click to toggle source

Raises CommunicationError and stores response in it if present

@param [StandardException] e upstream exception object

# File lib/mailgun/client.rb, line 202
def communication_error(e)
  return CommunicationError.new(e.message, e.response) if e.respond_to? :response
  CommunicationError.new(e.message)
end
convert_string_to_file(string) click to toggle source

Converts MIME string to file for easy uploading to API

@param [String] string MIME string to post to API @return [File] File object

# File lib/mailgun/client.rb, line 176
def convert_string_to_file(string)
  file = Tempfile.new('MG_TMP_MIME')
  file.write(string)
  file.rewind
  file
end
endpoint_generator(api_host, api_version, ssl) click to toggle source

Generates the endpoint URL to for the API. Allows overriding API endpoint, API versions, and toggling SSL.

@param [String] api_host URL endpoint the library will hit @param [String] api_version The version of the API to hit @param [Boolean] ssl True, SSL. False, No SSL. @return [string] concatenated URL string

# File lib/mailgun/client.rb, line 190
def endpoint_generator(api_host, api_version, ssl)
  ssl ? scheme = 'https' : scheme = 'http'
  if api_version
    "#{scheme}://#{api_host}/#{api_version}"
  else
    "#{scheme}://#{api_host}"
  end
end
perform_data_validation(working_domain, data) click to toggle source
# File lib/mailgun/client.rb, line 207
def perform_data_validation(working_domain, data)
  message = data.respond_to?(:message) ? data.message : data
  fail ParameterError.new('Missing working domain', working_domain) unless working_domain
  fail ParameterError.new(
    'Missing `to` recipient, message should containg at least 1 recipient',
    working_domain
  ) if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
  fail ParameterError.new(
    'Missing a `from` sender, message should containg at least 1 `from` sender',
    working_domain
  ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
end