# 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](https://lostisland.github.io/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](https://www.mailblastr.com/docs/integrations/nodejs).

## Prerequisites

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

## Net::HTTP (no dependencies)

**send.rb**

```ruby
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**

```ruby
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](https://www.mailblastr.com/docs/api/emails-get) or match [webhook](https://www.mailblastr.com/docs/webhooks/overview) events.

> **Warning:** 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

- See the full [Send Email API](https://www.mailblastr.com/docs/api/emails-send) reference.
- Read [Authentication](https://www.mailblastr.com/docs/authentication) for key permissions.
- Start from the [Quickstart](https://www.mailblastr.com/docs/quickstart).