DocumentationAPI ReferenceKnowledge Base
Send with your stack

Send emails with Ruby on Rails

Call the MailBlastr REST API from Ruby with the standard-library Net::HTTP, or with Faraday in Rails.

MailBlastr does not yet publish a Ruby gem, but Ruby's standard library covers it: Net::HTTP can POST /emails with no extra dependency. In a Rails app, the Faraday gem (often already a dependency) gives a tidier client. Both send your mb_ Bearer token.

This guide shows the dependency-free Net::HTTP path and a Rails-friendly Faraday alternative. Node.js projects can use npm install mailblastr instead — see Send emails with Node.js.

Prerequisites

  1. A verified domain for your from address. (guide)
  2. An API key (mb_...), read from ENV["MAILBLASTR_API_KEY"] (e.g. via Rails credentials). (Authentication)
  3. Ruby 3+ (for Net::HTTP) — Faraday is optional and typically already in a Rails Gemfile.

Net::HTTP (no dependencies)

send.rb
require "net/http"
require "json"
require "uri"

uri = URI("https://www.mailblastr.com/api/emails")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch('MAILBLASTR_API_KEY')}"
request["Content-Type"] = "application/json"
request.body = {
  from: "Acme <hello@yourdomain.com>",
  to: ["delivered@example.com"],
  subject: "Hello from Ruby",
  html: "<p>Sent with Net::HTTP 💎</p>"
}.to_json

response = http.request(request)
data = JSON.parse(response.body)

# MailBlastr returns { statusCode, name, message } on error.
unless response.is_a?(Net::HTTPSuccess)
  raise "MailBlastr #{data['name']}: #{data['message']}"
end

puts "Sent email #{data['id']}"

Faraday (Rails service object)

A small service object keeps the call out of your controllers. Read the key from Rails credentials or the environment.

app/services/mailblastr_client.rb
require "faraday"

class MailblastrClient
  BASE = "https://www.mailblastr.com/api".freeze

  def initialize(api_key: ENV.fetch("MAILBLASTR_API_KEY"))
    @conn = Faraday.new(url: BASE) do |f|
      f.request :json
      f.response :json
      f.headers["Authorization"] = "Bearer #{api_key}"
    end
  end

  def send_email(from:, to:, subject:, html:)
    res = @conn.post("/emails", { from: from, to: to, subject: subject, html: html })
    raise "MailBlastr #{res.body['name']}: #{res.body['message']}" unless res.success?

    res.body["id"]
  end
end

# id = MailblastrClient.new.send_email(
#   from: "Acme <hello@yourdomain.com>",
#   to: ["delivered@example.com"],
#   subject: "Hello from Rails",
#   html: "<p>Sent via a service object.</p>",
# )

Handling the response

On success MailBlastr returns HTTP 200 with { "id": "..." }; on failure a non-2xx status with { statusCode, name, message }. Check the status (Net::HTTPSuccess or Faraday's res.success?) before reading the id. Persist the id to retrieve the email or match webhook events.

Keep the mb_ API key server-side — in Rails credentials or an environment variable, never in client code or version control. Anyone with the key can send email as you.

Next steps