> ## Documentation Index
> Fetch the complete documentation index at: https://jetemail.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby

> Official JetEmail Ruby SDK for transactional email

# Ruby SDK

The **[jetemail](https://rubygems.org/gems/jetemail)** gem is the official Ruby SDK for JetEmail transactional email (MIT license, **Ruby 3.0+**).

Create a **transactional** API key in the dashboard: **Outbound** → **Keys** → Add API key. Use that key with the SDK.

## Installation

```bash theme={null}
gem install jetemail
```

Or add to your `Gemfile`:

```ruby theme={null}
gem "jetemail"
```

Gem on RubyGems: [jetemail](https://rubygems.org/gems/jetemail).

## Quick start

```ruby theme={null}
require "jetemail"

client = JetEmail::Client.new("your-transactional-api-key")

result = client.email.send(
  from: "Your App <hello@yourdomain.com>",
  to: "user@example.com",
  subject: "Welcome!",
  html: "<h1>Welcome!</h1>"
)

puts result["id"]
```

Use a `from` address on a **verified domain** (see [Getting started](/transactional-email/getting-started)).

## Constructor

```ruby theme={null}
# API key string
client = JetEmail::Client.new("your-transactional-api-key")

# Or with options
client = JetEmail::Client.new(
  api_key: "your-transactional-api-key",
  base_url: "https://api.jetemail.com" # optional
)
```

## `client.email.send(**options)`

Send a single email.

| Field                   | Required | Description                              |
| ----------------------- | -------- | ---------------------------------------- |
| `from`                  | ✓        | Sender, e.g. `"Name <email@domain.com>"` |
| `to`                    | ✓        | Recipient(s), string or array (max 50)   |
| `subject`               | ✓        | Subject line                             |
| `html`                  | \*       | HTML body (need `html` and/or `text`)    |
| `text`                  | \*       | Plain text (need `html` and/or `text`)   |
| `cc`, `bcc`, `reply_to` |          | Recipients (max 50 each)                 |
| `headers`               |          | Custom headers hash                      |
| `attachments`           |          | Attachments (max 40MB total)             |

Response shape: `{ "id" => String, "response" => String }`.

## `client.batch.send(emails)`

Send up to **100** emails in one request. Returns `summary` (`total`, `successful`, `failed`) and `results` per message.

```ruby theme={null}
result = client.batch.send([
  {
    from: "you@example.com",
    to: "alice@example.com",
    subject: "Hello Alice",
    html: "<p>Hi Alice!</p>"
  },
  {
    from: "you@example.com",
    to: "bob@example.com",
    subject: "Hello Bob",
    html: "<p>Hi Bob!</p>"
  }
])
```

## Attachments

```ruby theme={null}
result = client.email.send(
  from: "you@example.com",
  to: "recipient@example.com",
  subject: "Invoice",
  html: "<p>Please find your invoice attached.</p>",
  attachments: [
    JetEmail::Attachment.from_path("/path/to/invoice.pdf"),
    JetEmail::Attachment.from_content("Hello World", "hello.txt")
  ]
)
```

## Error handling

```ruby theme={null}
begin
  client.email.send(...)
rescue JetEmail::JetEmailError => e
  puts e.status_code
  puts e.message
  puts e.response
end
```

Common status codes: **400** invalid request, **401** bad/missing API key, **500** server error.

***

For additional examples and the full option list, see the **[RubyGems page](https://rubygems.org/gems/jetemail)**. REST details: [API reference](/api-reference/introduction).