class Mailgun::Client

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

def self.deliveries

Returns:
  • (Hash) -
def self.deliveries
  @@deliveries ||= []
end

def api_version

Returns:
  • (String) - client api version
def api_version
  @api_version
end

def communication_error(e)

Parameters:
  • e (StandardException) -- upstream exception object
def communication_error(e)
  if e.respond_to?(:response) && e.response
    return case e.response_status
    when Unauthorized::CODE
      Unauthorized.new(e.message, e.response)
    when BadRequest::CODE
      BadRequest.new(e.message, e.response)
    else
      CommunicationError.new(e.message, e.response)
    end
  end
  CommunicationError.new(e.message)
end

def convert_string_to_file(string)

Returns:
  • (File) - File object

Parameters:
  • string (String) -- MIME string to post to API
def convert_string_to_file(string)
  file = Tempfile.new('MG_TMP_MIME')
  file.write(string)
  file.rewind
  file
end

def delete(resource_path, params = nil)

Returns:
  • (Mailgun::Response) - A Mailgun::Response object.

Parameters:
  • resource_path (String) -- This is the API resource you wish to interact
def delete(resource_path, params = nil)
  if params
    response = @http_client.delete(resource_path, params: params)
  else
    response = @http_client.delete(resource_path)
  end
  Response.new(response)
rescue => err
  raise communication_error err
end

def disable_test_mode!

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

Disable test mode
def disable_test_mode!
  @test_mode = false
end

def enable_test_mode!

Prevents sending of any messages.

Enable test mode
def enable_test_mode!
  @test_mode = true
end

def endpoint_generator(api_host, api_version, ssl)

Returns:
  • (string) - concatenated URL string

Parameters:
  • ssl (Boolean) -- True, SSL. False, No SSL.
  • api_version (String) -- The version of the API to hit
  • api_host (String) -- URL endpoint the library will hit
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

def get(resource_path, params = {}, accept = '*/*')

Raises:
  • (CommunicationError) - If the request fails, raises a communication error.

Returns:
  • (Mailgun::Response) - A response object containing the API response data.

Parameters:
  • accept (String) -- The expected Content-Type of the response. Defaults to '*/*'.
  • params (Hash) -- Optional request parameters, including query parameters and headers.
  • resource_path (String) -- The API resource path to request, including the domain if required.
def get(resource_path, params = {}, accept = '*/*')
  headers = (params[:headers] || {}).merge(accept: accept)
  response = @http_client.get(resource_path, params, headers)
  Response.new(response)
rescue => err
  raise communication_error(err)
end

def initialize(api_key = Mailgun.api_key,

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)
  endpoint = endpoint_generator(api_host, api_version, ssl)
  request_options = {
    url: endpoint,
    proxy: Mailgun.proxy_url,
    ssl: {verify: ssl},
    headers: {
               'User-Agent' => "mailgun-sdk-ruby/#{Mailgun::VERSION}",
               'Accept' =>'*/*'
              }
  }
  request_options.merge!(request: {timeout: timeout}) if timeout
  @http_client =  Faraday.new(request_options) do |conn|
    conn.request :multipart
    conn.request :authorization, :basic, 'api', api_key
    conn.request :url_encoded
    conn.response :raise_error, include_request: true
    conn.adapter Faraday.default_adapter
    conn.options.params_encoder = Faraday::FlatParamsEncoder
  end
  @test_mode = test_mode
  @api_version = api_version
end

def perform_data_validation(working_domain, data)

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 contain at least 1 recipient',
    working_domain
  ) if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
  fail ParameterError.new(
    'Missing a `from` sender, message should contain at least 1 `from` sender',
    working_domain
  ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
end

def post(resource_path, data, headers = {})

Returns:
  • (Mailgun::Response) - A Mailgun::Response object.

Parameters:
  • headers (Hash) -- Additional headers to pass to the resource.
  • data (Hash) -- This should be a standard Hash
  • resource_path (String) -- This is the API resource you wish to interact
def post(resource_path, data, headers = {})
  response = @http_client.post(resource_path, data, headers)
  Response.new(response)
rescue => err
  raise communication_error err
end

def put(resource_path, data)

Returns:
  • (Mailgun::Response) - A Mailgun::Response object.

Parameters:
  • data (Hash) -- This should be a standard Hash
  • resource_path (String) -- This is the API resource you wish to interact
def put(resource_path, data)
  response = @http_client.put(resource_path, data)
  Response.new(response)
rescue => err
  raise communication_error err
end

def reset_subaccount

Reset subaccount for primary usage
def reset_subaccount
  @http_client.headers.delete(SUBACCOUNT_HEADER)
end

def send_message(working_domain, data)

Returns:
  • (Mailgun::Response) - A Mailgun::Response object.

Parameters:
  • data (Hash) -- This should be a standard Hash
  • working_domain (String) -- This is the domain you wish to send from.
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.\"}",
        :status => 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

def set_api_key(api_key)

Change API key
def set_api_key(api_key)
  @http_client.set_basic_auth('api', api_key)
end

def set_subaccount(subaccount_id)

Add subaccount id to headers
def set_subaccount(subaccount_id)
  @http_client.headers = @http_client.headers.merge!({ SUBACCOUNT_HEADER => subaccount_id })
end

def suppressions(domain)

Returns:
  • (Mailgun::Suppressions) -

Parameters:
  • domain (String) -- Domain which suppressions requests will be made for
def suppressions(domain)
  Suppressions.new(self, domain)
end

def test_mode?

Returns:
  • (Boolean) - Is the client set in test mode?
def test_mode?
  @test_mode
end