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

new(api_key, api_host="api.mailgun.net", api_version="v3", ssl=true) click to toggle source
# File lib/mailgun.rb, line 23
def initialize(api_key,
               api_host="api.mailgun.net",
               api_version="v3",
               ssl=true)

  endpoint = endpoint_generator(api_host, api_version, ssl)
  @http_client = RestClient::Resource.new(endpoint,
                                          :user => "api",
                                          :password => api_key,
                                          :user_agent => "mailgun-sdk-ruby/#{Mailgun::VERSION}",
                                          :ssl_version => "TLSv1")
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.rb, line 129
def delete(resource_path)
  begin
    response = @http_client[resource_path].delete()
    Response.new(response)
  rescue Exception => e
    communication_error e
  end
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] query_string This should be a standard Hash containing required parameters for the requested resource. @return [Mailgun::Response] A Mailgun::Response object.

# File lib/mailgun.rb, line 93
def get(resource_path, params=nil, accept="*/*")
  begin
    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 Exception => e
    communication_error e
  end
end
post(resource_path, data) 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. @return [Mailgun::Response] A Mailgun::Response object.

# File lib/mailgun.rb, line 76
def post(resource_path, data)
  begin
    response = @http_client[resource_path].post(data)
    Response.new(response)
  rescue Exception => e
    communication_error e
  end
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.rb, line 114
def put(resource_path, data)
  begin
    response = @http_client[resource_path].put(data)
    Response.new(response)
  rescue Exception => e
    communication_error e
  end
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.rb, line 43
def send_message(working_domain, data)
  case data
  when Hash
    if data.has_key?(:message)
      if data[:message].is_a?(String)
        data[:message] = convert_string_to_file(data[:message])
      end
      post("#{working_domain}/messages.mime", data)
    else
      post("#{working_domain}/messages", data)
    end
  when MessageBuilder
    post("#{working_domain}/messages", data.message)
  else
    raise ParameterError.new("Unknown data type for data parameter.", data)
  end
end
validate_email(email) click to toggle source

Validate an email address

@param [String] email This is the email address you wish to validate

# File lib/mailgun.rb, line 64
def validate_email(email)
  get('/address/validate', {address: email})
end

Private Instance Methods

communication_error(e) click to toggle source

Raises CommunicationError and stores response in it if present

@param [Exception] e upstream exception object

# File lib/mailgun.rb, line 173
def communication_error(e)
  if e.respond_to? :response
    raise CommunicationError.new(e.message, e.response)
  else
    raise CommunicationError.new(e.message)
  end
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.rb, line 145
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.rb, line 160
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