Mailtrap Ruby Client

https://github.com/mailtrap/mailtrap-ruby
Admin
A Ruby gem that provides an official client for integrating with the Mailtrap API to quickly add...
Tokens:107,701
Snippets:702
Trust Score:8.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### InboundFoldersAPI Usage Example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/inbound-apis.md

Example demonstrating folder creation, update, and deletion.

```ruby
folders = Mailtrap::InboundFoldersAPI.new
folder = folders.create(name: 'Support')
folders.update(folder.id, name: 'Support 2025')
folders.delete(folder.id)
```

--------------------------------

### Usage example: list, get, reply, forward

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/inbound-apis.md

Demonstrates paginating through messages, fetching a message's text body, and sending reply, reply_all, and forward actions; prints the resulting message_ids.

```ruby
messages = Mailtrap::InboundMessagesAPI.new

page = messages.list(5)
while page.last_id
  page = messages.list(5, last_id: page.last_id)
end

first = page.data.first
puts messages.get(5, first.id).text_body

result = messages.reply(5, first.id, text: 'Thanks for your email!')
result = messages.reply_all(5, first.id, text: 'Reply to everyone')
result = messages.forward(5, first.id, to: ['agent@example.com'], text: 'Please handle')
puts result.message_ids
```

--------------------------------

### EmailCampaignsAPI Usage Example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-marketing-apis.md

A comprehensive example demonstrating campaign creation, scheduling, lifecycle management, and statistics retrieval.

```ruby
campaigns = Mailtrap::EmailCampaignsAPI.new(account_id: 123)

campaign = campaigns.create(
  name: 'Spring promo',
  domain_id: 7,
  from_local_part: 'news',
  from_display_name: 'Example Store',
  template_attributes: { subject: 'Spring sale', body_html: '<p>Sale!</p>' },
  delivery_mode: 'rapid',
  contact_list_ids: [1]
)

campaign = campaigns.schedule(campaign.id, (Time.now + 3600).utc.iso8601)
campaign = campaigns.cancel(campaign.id)
campaign = campaigns.start(campaign.id)
stats = campaigns.stats(campaign.id)
puts "delivered=#{stats.delivery_count} open_rate=#{stats.open_rate}"
campaigns.terminate(campaign.id)   # if still in flight
```

--------------------------------

### ProjectsAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/sandbox-apis.md

Example demonstrating project creation, iteration over inboxes, updating, and deletion.

```ruby
projects = Mailtrap::ProjectsAPI.new(account_id: 123)
project = projects.create(name: 'My App')
project.inboxes.each { |inbox| puts inbox.name }
projects.update(project.id, name: 'My App v2')
projects.delete(project.id)
```

--------------------------------

### Add Attachment Example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/mail.md

Example of adding an attachment to the email instance.

```ruby
mail.add_attachment(content: Base64.strict_encode64('data'), filename: 'note.txt', type: 'text/plain')
```

--------------------------------

### EmailCampaignsAPI#start

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-marketing-apis.md

Starts a draft email campaign immediately. Returns the updated campaign object.

```APIDOC
## EmailCampaignsAPI#start

### Description
Starts a draft email campaign immediately. Returns the updated campaign object.

### Method
POST

### Endpoint
/api/email_campaigns/{id}/start

### Parameters
#### Path Parameters
- **email_campaign_id** (Integer) - Required - The ID of the email campaign to start.

### Response
#### Success Response (200)
- **EmailCampaign** (Object) - The updated campaign object.

#### Response Example
{
  "id": 1,
  "status": "started"
}
```

--------------------------------

### List attachments example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/sandbox-apis.md

Example usage: creates a SandboxAttachmentsAPI instance and lists attachments, printing filename and human-readable size for each.

```ruby
attachments = Mailtrap::SandboxAttachmentsAPI.new(account_id: 123, inbox_id: 42, sandbox_message_id: 7)
attachments.list.each { |a| puts "#{a.filename} #{a.attachment_human_size}" }
```

--------------------------------

### ContactExportsAPI create/get usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-import-export-apis.md

Example usage of the ContactExportsAPI create and get methods. It creates an export with a filter, waits, retrieves the export, and prints the URL if the export is finished.

```ruby
exports = Mailtrap::ContactExportsAPI.new(account_id: 123)
export = exports.create(filters: [{ name: 'subscription_status', operator: 'equal', value: 'subscribed' }])
sleep 2
export = exports.get(export.id)
puts export.url if export.status == 'finished'

```

--------------------------------

### InboundInboxesAPI Usage Example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/inbound-apis.md

Example demonstrating inbox creation, update, retrieval, and deletion.

```ruby
inboxes = Mailtrap::InboundInboxesAPI.new
inbox = inboxes.create(3, name: 'Main inbox', domain_id: 7)   # custom domain
inbox = inboxes.update(3, inbox.id, name: 'Main inbox v2')
puts inboxes.get(3, inbox.id).address
inboxes.delete(3, inbox.id)
```

--------------------------------

### ContactImportsAPI create/start usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-import-export-apis.md

Example usage of the ContactImportsAPI create/start methods. It shows creating an import with a request builder or plain hashes, then retrieving the import status.

```ruby
imports = Mailtrap::ContactImportsAPI.new(account_id: 123)

import = imports.create(request)                      # builder from above
# or plain hashes:
import = imports.start([
  { email: 'john@example.com', fields: { first_name: 'John' }, list_ids_included: [1], list_ids_excluded: [2] }
])

puts imports.get(import.id).status

```

--------------------------------

### InboxesAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/sandbox-apis.md

Example demonstrating inbox creation, updating, maintenance operations, and deletion.

```ruby
inboxes = Mailtrap::InboxesAPI.new(account_id: 123)
inbox = inboxes.create(project_id: 4, name: 'Staging')
inbox = inboxes.update(inbox.id, name: 'Staging 2')
inbox = inboxes.mark_as_read(inbox.id)
inbox = inboxes.clean(inbox.id)
inboxes.delete(inbox.id)
```

--------------------------------

### InboundThreadsAPI Usage Example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/inbound-apis.md

A complete workflow example demonstrating listing threads, retrieving a specific thread, iterating through its messages, and deleting the thread.

```ruby
threads = Mailtrap::InboundThreadsAPI.new
page = threads.list(5)
thread = threads.get(5, page.data.first.id)
thread.messages.each { |m| puts "#{m.direction} #{m.subject} (#{m.visibility_status})" }
threads.delete(5, thread.id)
```

--------------------------------

### SendingDomainsAPI send_setup_instructions method

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-sending-apis.md

Sends domain setup instructions to the specified email address.

```ruby
def send_setup_instructions(domain_id, email:)   # line 74
```

--------------------------------

### from_content usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/mail.md

Creates a mail object using from_content and sends it via client.send. The example includes from, to, subject, text, and category parameters.

```ruby
mail = Mailtrap::Mail.from_content(
  from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
  to: [{ email: 'your@email.com', name: 'Your name' }],
  subject: 'You are awesome!',
  text: 'Congrats!',
  category: 'Integration Test'
)
client.send(mail)
```

--------------------------------

### ContactEventsAPI#create usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-import-export-apis.md

Shows how to instantiate ContactEventsAPI and create an event for a contact. The example uses an account ID of 123 and creates an event with name 'upgraded' and params { plan: 'pro' }.

```ruby
events = Mailtrap::ContactEventsAPI.new(account_id: 123)
event = events.create('jane@example.com', name: 'upgraded', params: { plan: 'pro' })
puts event.contact_email

```

--------------------------------

### ContactImportsAPI#create (alias start) method

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-import-export-apis.md

Defines the create method (aliased as start) for the ContactImportsAPI class. It accepts a Mailtrap::ContactsImportRequest or an array of hashes, validates each hash against supported_options, and POSTs the data to the contacts imports endpoint.

```ruby
def create(contacts)   # line 46
alias start create

```

--------------------------------

### from_template usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/mail.md

Creates a mail object using from_template with a template UUID and variables. The example includes from, to, template_uuid, and template_variables.

```ruby
mail = Mailtrap::Mail.from_template(
  from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
  to: [{ email: 'your@email.com' }],
  template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
  template_variables: { 'user_name' => 'John Doe' }
)
```

--------------------------------

### Install Mailtrap Gem

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/README.md

Add the gem to your Gemfile and install it via Bundler or directly via the command line.

```ruby
gem 'mailtrap'
```

```bash
$ bundle install
```

```bash
$ gem install mailtrap
```

--------------------------------

### ContactListsAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-crud-apis.md

Example usage of ContactListsAPI: create a list, update its name, search lists with a prefix filter, and delete the list. Demonstrates the typical workflow for managing contact lists.

```ruby
lists = Mailtrap::ContactListsAPI.new(account_id: 123)
list = lists.create(name: 'Newsletter')
lists.update(list.id, name: 'Newsletter v2')
lists.list(search: 'News').each { |l| puts l.name }
lists.delete(list.id)
```

--------------------------------

### POST /api/email_campaigns/{id}/start

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/endpoints.md

Starts sending an email campaign.

```APIDOC
## POST /api/email_campaigns/{id}/start

### Description
Starts an email campaign.

### Method
POST

### Endpoint
/api/email_campaigns/{id}/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the email campaign.

### Response
#### Success Response (200)
- **data** (object) - The email campaign object.

#### Response Example
{
  "data": {}
}
```

--------------------------------

### CompanyInfoAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-sending-apis.md

Example of creating and updating company info using Mailtrap::CompanyInfoAPI. Requires account_id and sending_domain_id. info_level must be 'business' or 'individual'.

```ruby
info = Mailtrap::CompanyInfoAPI.new(account_id: 123)
created = info.create(42, name: 'Example Inc', city: 'Kyiv', country: 'UA', info_level: 'business')
info.update(42, website_url: 'https://example.com')
```

--------------------------------

### ContactsAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-crud-apis.md

Demonstrates creating, upserting, modifying lists, and deleting a contact.

```ruby
contacts = Mailtrap::ContactsAPI.new(account_id: 123)

created = contacts.create(email: 'jane@example.com', fields: { first_name: 'Jane' }, list_ids: [1])
created.newly_created?   # => true

contact = contacts.upsert('jane@example.com', fields: { last_name: 'Doe' })   # creates if missing
contact = contacts.add_to_lists('jane@example.com', [2, 3])
contact = contacts.remove_from_lists('jane@example.com', [1])
contacts.delete(contact.id)
```

--------------------------------

### StatsAPI usage example: overall and grouped stats

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-logs-stats-apis.md

Example of using StatsAPI to fetch overall stats and stats grouped by domain. Shows how to access delivery_count, delivery_rate, and open_count from the returned objects.

```ruby
stats = Mailtrap::StatsAPI.new(account_id: 123)

overall = stats.get(start_date: '2025-01-01', end_date: '2025-01-31')
puts "delivered #{overall.delivery_count} (rate #{overall.delivery_rate})"

stats.by_domain(start_date: Date.new(2025, 1, 1), end_date: Date.new(2025, 1, 31)).each do |g|
  puts "#{g.name}=#{g.value}: opens #{g.stats.open_count}"
end
```

--------------------------------

### Rackup example for webhook signature verification

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/webhooks.md

Example Rack application that verifies webhook signatures on POST /webhooks/mailtrap. It reads the raw body, fetches the signature header, and verifies using Mailtrap::Webhooks.verify_signature. Returns 401 on invalid signature.

```ruby
require 'mailtrap'
require 'rack'

SIGNING_SECRET = ENV.fetch('MAILTRAP_WEBHOOK_SIGNING_SECRET')

app = lambda do |env|
  request = Rack::Request.new(env)
  next [404, { 'content-type' => 'text/plain' }, ['Not Found']] unless request.post? && request.path == '/webhooks/mailtrap'

  payload   = request.body.read                     # raw body — do not re-parse
  signature = env['HTTP_MAILTRAP_SIGNATURE']

  if Mailtrap::Webhooks.verify_signature(payload: payload, signature: signature, signing_secret: SIGNING_SECRET)
    # signature is valid — process the event
    [200, { 'content-type' => 'text/plain' }, ['OK']]
  else
    [401, { 'content-type' => 'text/plain' }, ['Invalid signature']]
  end
end

run app
```

--------------------------------

### ContactImportsAPI create error handling example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-import-export-apis.md

Example of error handling when creating a contact import with an invalid option key (missing email). It rescues ArgumentError and prints the error message.

```ruby
begin
  imports.create([{ fields: { first_name: 'x' } }])   # email missing → invalid option key
rescue ArgumentError => e
  warn e.message
end

```

--------------------------------

### CompanyInfoAPI method signatures (get, create, update)

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-sending-apis.md

Method signatures for CompanyInfoAPI: get(sending_domain_id), create(sending_domain_id, options), update(sending_domain_id, options). All return a CompanyInfo built from response[:data]. Raises ArgumentError or Mailtrap::Error subclasses.

```ruby
def get(sending_domain_id)            # line 29
def create(sending_domain_id, options) # line 50
def update(sending_domain_id, options) # line 62
```

--------------------------------

### Mailtrap::Client - Basic Construction Example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/client.md

Shows how to create a client with an explicit API key, and demonstrates equivalent construction using the MAILTRAP_API_KEY environment variable. Also covers sandbox, bulk, and custom endpoint variations with different host and port values.

```ruby
require 'mailtrap'

client = Mailtrap::Client.new(api_key: 'your-api-key')

# Equivalent: Mailtrap::Client.new with MAILTRAP_API_KEY env var set
# env_client = Mailtrap::Client.new

# Sandbox, bulk, or custom endpoints:
sandbox_client = Mailtrap::Client.new(api_key: 'your-api-key', sandbox: true, inbox_id: 42)
bulk_client    = Mailtrap::Client.new(api_key: 'your-api-key', bulk: true)
custom_client  = Mailtrap::Client.new(api_key: 'your-api-key', api_host: 'alt.mailtrap.io', api_port: 8443)
```

--------------------------------

### StatsAPI error handling for invalid date

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-logs-stats-apis.md

Example of rescuing an ArgumentError when an invalid date format is passed to the get method. The error message includes the invalid date and the expected format.

```ruby
begin
  stats.get(start_date: '2025/01/01', end_date: '2025-01-31')
rescue ArgumentError => e
  warn e.message   # Invalid date: "2025/01/01". Expected a Date, Time, or String in YYYY-MM-DD format.
end
```

--------------------------------

### SandboxAttachmentsAPI get and list methods

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/sandbox-apis.md

Defines the get and list methods. get returns a SandboxAttachment, list returns an Array<SandboxAttachment> (≤ 30). Both raise Mailtrap::Error subclasses.

```ruby
def get(sandbox_attachment_id)   # line 34
def list                        # line 41
```

--------------------------------

### Initializing API classes

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/base_api.md

Examples of initializing an API class using environment variables or explicit client configuration.

```ruby
# MAILTRAP_ACCOUNT_ID and MAILTRAP_API_KEY are both set
api = Mailtrap::ProjectsAPI.new

# explicit
client = Mailtrap::Client.new(api_key: 'key')
api = Mailtrap::ProjectsAPI.new(account_id: 123, client: client)
```

--------------------------------

### POST /api/accounts/{id}/sending_domains/{domain_id}/send_setup_instructions

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/endpoints.md

Sends setup instructions for a sending domain to a specified email address.

```APIDOC
## POST /api/accounts/{id}/sending_domains/{domain_id}/send_setup_instructions

### Description
Sends setup instructions for a sending domain to a specified email address.

### Method
POST

### Endpoint
/api/accounts/{id}/sending_domains/{domain_id}/send_setup_instructions

### Parameters
#### Path Parameters
- **id** (string) - Required - The account ID.
- **domain_id** (string) - Required - The sending domain ID.

#### Request Body
- **email** (string) - Required - The email address to send instructions to.

### Request Example
{
  "email": "user@example.com"
}

### Response
#### Success Response (200)
- **raw response** - The raw response body.
```

--------------------------------

### AccountsAPI#initialize

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/account-management-apis.md

Constructor for AccountsAPI. Takes only a client; account_id is not used. Expects the API key to be available to the client.

```APIDOC
## AccountsAPI#initialize

### Description
Overrides the BaseAPI constructor - takes only a client; account_id is not used (the endpoint lists all accounts). Expects the API key to be available to the client.

### Method
Constructor

### Signature
```ruby
def initialize(client = Mailtrap::Client.new)
```

### Parameters
- **client** (Mailtrap::Client) - Optional - Default: `Mailtrap::Client.new` - Transport

### Example
```ruby
api = Mailtrap::AccountsAPI.new(client: Mailtrap::Client.new(api_key: 'key'))
```
```

--------------------------------

### EmailTemplatesAPI Usage Example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-marketing-apis.md

Demonstrates initializing the API, creating a template, updating its category, listing templates, and deleting a template.

```ruby
templates = Mailtrap::EmailTemplatesAPI.new(account_id: 123)
tpl = templates.create(name: 'Welcome', subject: 'Welcome!', body_html: '<h1>Hi</h1>')
templates.update(tpl.id, category: 'Onboarding')
templates.list.each { |t| puts t.name }
templates.delete(tpl.id)
```

--------------------------------

### ContactsAPI error handling example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-crud-apis.md

Example of catching Mailtrap::Error when an API request fails.

```ruby
begin
  contacts.create(fields: { first_name: 'No email' })   # missing email — server 4xx
rescue Mailtrap::Error => e
  warn e.messages.inspect
end
```

--------------------------------

### SendingDomainsAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-sending-apis.md

Demonstrates creating, updating, sending instructions, and listing domains using the SendingDomainsAPI.

```ruby
domains = Mailtrap::SendingDomainsAPI.new(account_id: 123)
d = domains.create(domain_name: 'example.com')
domains.update(d.id, open_tracking_enabled: true, click_tracking_enabled: false)
domains.send_setup_instructions(d.id, email: 'admin@example.com')
domains.list.each { |dom| puts "#{dom.domain_name} verified=#{dom.dns_verified}" }
```

--------------------------------

### AccountsAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/account-management-apis.md

Creates an AccountsAPI instance with a client using an API key, lists accounts, and prints each account's id, name, and access levels.

```ruby
api = Mailtrap::AccountsAPI.new(client: Mailtrap::Client.new(api_key: 'key'))
accounts = api.list
accounts.each { |acc| puts "#{acc.id}: #{acc.name} (#{acc.access_levels.inspect})" }
```

--------------------------------

### get and delete method signatures (lines 43, 52)

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/inbound-apis.md

Defines get and delete methods for a specific message in an inbox.

```ruby
def get(inbox_id, message_id)    # line 43
def delete(inbox_id, message_id) # line 52
```

--------------------------------

### Initialize Mailtrap::Mail::Base

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/mail.md

Example of creating a new email instance with recipient and template variables.

```ruby
mail = Mailtrap::Mail::Base.new(
  to: [{ email: 'jane.doe@email.com' }],
  template_variables: { user_name: 'Jane Doe' }
)
```

--------------------------------

### ContactImportsAPI#get method

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-import-export-apis.md

Defines the get method for the ContactImportsAPI class. It retrieves a contact import by its ID and returns a ContactImport object.

```ruby
def get(import_id)   # line 18

```

--------------------------------

### base_create(options, override = supported_options)

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/base_api.md

Creates a new resource. Validates options against supported_options, sends a POST request with the wrapped request body, and processes the response.

```APIDOC
## base_create(options, override = supported_options)

### Description
Creates a new resource. Validates the provided options against the allowed list, sends a POST request to the base_path with the wrapped request body, and processes the response.

### Method
POST

### Endpoint
`#{base_path}`

### Parameters
- **options** (Hash) - Required - The attributes for the new resource.
- **override** (Array<Symbol>) - Optional - Default: `supported_options` - The list of allowed option keys for validation.

### Raises
- `ArgumentError` - If any option key is not in the allowed list.

### Response
Returns the response processed by `handle_response`, typically a Struct instance.

### Example
ruby
api.base_create({ name: 'New Project' })

```

--------------------------------

### Mailtrap::Client.new

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/client.md

Initializes a new Mailtrap API client. Accepts an API key and optional configuration for host, port, bulk, sandbox, and inbox ID. Raises ArgumentError or KeyError on invalid configuration.

```APIDOC
## Mailtrap::Client.new

### Description
Initializes a new Mailtrap API client. Accepts an API key and optional configuration for host, port, bulk, sandbox, and inbox ID. Raises ArgumentError or KeyError on invalid configuration.

### Method
Constructor

### Endpoint
N/A (SDK constructor)

### Parameters
#### Constructor Parameters
- **api_key** (String) - Optional* - API key. *If omitted, read from the `MAILTRAP_API_KEY` env var; `ENV.fetch` raises `KeyError` when the var is unset. `validate_args!` raises `ArgumentError` if it is `nil`.
- **api_host** (String) - Optional - Sending host. When `nil`, selected automatically: `SANDBOX_API_HOST` if `sandbox`, `BULK_SENDING_API_HOST` if `bulk`, otherwise `SENDING_API_HOST`.
- **general_api_host** (String) - Optional - Host for non-sending operations (`get`/`post`/`patch`/`put`/`delete`). Default: `GENERAL_API_HOST` (`mailtrap.io`).
- **api_port** (Integer) - Optional - Connection port. Default: `API_PORT` (443). `ArgumentError` if `nil`.
- **bulk** (Boolean) - Optional - Use the bulk sending API. Incompatible with `sandbox: true` (raises `ArgumentError`). Default: `false`.
- **sandbox** (Boolean) - Optional - Use the sandbox API (paths gain the inbox segment). Incompatible with `bulk: true`. Default: `false`.
- **inbox_id** (Integer) - Optional - Sandbox inbox ID; required when `sandbox: true`, otherwise `ArgumentError`. Default: `nil`.

### Request Example
```ruby
require 'mailtrap'

client = Mailtrap::Client.new(api_key: 'your-api-key')

# Equivalent: Mailtrap::Client.new with MAILTRAP_API_KEY env var set
# env_client = Mailtrap::Client.new

# Sandbox, bulk, or custom endpoints:
sandbox_client = Mailtrap::Client.new(api_key: 'your-api-key', sandbox: true, inbox_id: 42)
bulk_client    = Mailtrap::Client.new(api_key: 'your-api-key', bulk: true)
custom_client  = Mailtrap::Client.new(api_key: 'your-api-key', api_host: 'alt.mailtrap.io', api_port: 8443)
```

### Response
#### Success Response
- No return value (constructor)

#### Error Handling
- **ArgumentError** - Raised when `api_key` is `nil`, `api_port` is `nil`, `bulk && sandbox` is true, or `sandbox && inbox_id.nil?`.
- **KeyError** - Raised when neither `api_key` nor the `MAILTRAP_API_KEY` env var is present.

#### Error Example
```ruby
begin
  Mailtrap::Client.new(api_key: nil)                     # ArgumentError: api_key is required
  Mailtrap::Client.new(sandbox: true)                    # ArgumentError: inbox_id is required for sandbox API
  Mailtrap::Client.new(bulk: true, sandbox: true)        # ArgumentError: bulk stream is not applicable...
  Mailtrap::Client.new                                   # KeyError (no MAILTRAP_API_KEY env var)
rescue ArgumentError, KeyError => e
  warn "client configuration failed: #{e.message}"
end
```
```

--------------------------------

### SandboxMessagesAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/sandbox-apis.md

Shows typical usage: creating an API instance, iterating messages with list_each, retrieving a message, and calling various helpers. Demonstrates the methods documented above.

```ruby
messages = Mailtrap::SandboxMessagesAPI.new(account_id: 123, inbox_id: 42)

messages.list_each(search: 'welcome') do |m|
  puts "#{m.subject} size=#{m.human_size} read=#{m.read?}"
end

msg = messages.get(1)
puts messages.text_body(1)
puts messages.html_body(1)
puts messages.spam_score(1).inspect
messages.mark_as_read(1, is_read: true)
messages.forward_message(1, email: 'ops@example.com')
messages.delete(1)
```

--------------------------------

### base_get(id)

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/base_api.md

Performs a GET request to retrieve a single resource by ID. Uses the client's get method with the base_path and ID.

```APIDOC
## base_get(id)

### Description
Retrieves a single resource by its ID. Sends a GET request to `#{base_path}/#{id}` and processes the response.

### Method
GET

### Endpoint
`#{base_path}/#{id}`

### Parameters
- **id** (Integer/String) - Required - The ID of the resource to retrieve.

### Response
Returns the response processed by `handle_response`, typically a Struct instance.

### Example
ruby
api.base_get(123)

```

--------------------------------

### initialize(account_id, client)

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/base_api.md

Constructor for API classes that include BaseAPI. Accepts an account ID and a Mailtrap client, with defaults from environment variables.

```APIDOC
## initialize(account_id, client)

### Description
Creates a new instance of an API class that includes BaseAPI. The account ID is used in request paths, and the client handles transport.

### Method
Constructor

### Parameters
- **account_id** (Integer) - Optional - Default: `ENV.fetch('MAILTRAP_ACCOUNT_ID')` - Account ID used in request paths. Raises `KeyError` if env var is unset and no value is passed.
- **client** (Mailtrap::Client) - Optional - Default: `Mailtrap::Client.new` - Transport client. A fresh client is built when omitted, requiring `MAILTRAP_API_KEY` to be set.

### Raises
- `ArgumentError` - 'account_id is required' when `account_id` is `nil`.

### Example
ruby
# MAILTRAP_ACCOUNT_ID and MAILTRAP_API_KEY are both set
api = Mailtrap::ProjectsAPI.new

# explicit
client = Mailtrap::Client.new(api_key: 'key')
api = Mailtrap::ProjectsAPI.new(account_id: 123, client: client)

```

--------------------------------

### get

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/client.md

Performs a GET request to the Mailtrap API. Accepts a path and optional query parameters. Returns parsed JSON, raw body, or nil on 204.

```APIDOC
## get

### Description
Performs a GET request to the Mailtrap API. Accepts a path and optional query parameters. Returns parsed JSON, raw body, or nil on 204.

### Method
GET

### Endpoint
`GET {general_api_host}{path}?query`

### Parameters
#### Path Parameters
- `path` (String) - Required - Request path, e.g. `/api/accounts/123/projects`.

#### Query Parameters
- `query_params` (Hash) - Optional - URL-encoded query parameters (`URI.encode_www_form`).

### Request Example
```ruby
client = Mailtrap::Client.new(api_key: 'your-api-key')

client.get('/api/accounts/123/projects')                       # GET with no query
client.get('/api/accounts/123/inboxes', { page: 2 })           # GET with query params
```

### Response
#### Success Response
- **Returns:** `Hash, String, nil` — same parse policy as `send`.

#### Error Handling
- Raises: the same `Mailtrap::Error` family as `send` (see [errors.md](../errors.md)); `ArgumentError "Unsupported HTTP method: ..."` only for internal misuse (line 283).
```

--------------------------------

### EmailCampaignsAPI Constructor

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-marketing-apis.md

Initializes the EmailCampaignsAPI client.

```ruby
def initialize(client = Mailtrap::Client.new)   # line 26
```

--------------------------------

### ContactExportsAPI#get method

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-import-export-apis.md

Defines the get method for the ContactExportsAPI class. It retrieves a contact export by its ID and returns a ContactExport object. The url is populated when status is 'finished'.

```ruby
def get(export_id)   # line 18

```

--------------------------------

### batch_base_from_content usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/mail.md

Builds a batch base from content, adds an attachment, and sends a batch with two recipient-specific mails using client.send_batch.

```ruby
batch_base = Mailtrap::Mail.batch_base_from_content(
  from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
  subject: 'You are awesome!',
  text: 'Congrats!'
)
batch_base.add_attachment(content: File.open('attachment.txt'), filename: 'attachment.txt')
client.send_batch(batch_base, [
  Mailtrap::Mail.from_content(to: [{ email: 'john@example.com' }]),
  Mailtrap::Mail.from_content(to: [{ email: 'jane@example.com' }])
])
```

--------------------------------

### Constructor (line 18)

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/inbound-apis.md

Initializes the API client. Accepts an optional Mailtrap::Client instance, defaulting to a new one.

```ruby
def initialize(client = Mailtrap::Client.new)   # line 18
```

--------------------------------

### SuppressionsAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-sending-apis.md

Example of creating, listing, and deleting suppressions using Mailtrap::SuppressionsAPI. Requires account_id. create returns a Suppression, list returns an array, delete returns a Suppression.

```ruby
suppressions = Mailtrap::SuppressionsAPI.new(account_id: 123)
s = suppressions.create(email: 'spammer@example.com', sending_stream: 'bulk')
suppressions.list(email: 'spammer@example.com').each { |x| puts x.type }
suppressions.delete(s.id)
```

--------------------------------

### Mailtrap::ActionMailer::DeliveryMethod#initialize

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/action_mailer.md

Initializes a new delivery method instance with the provided settings. ActionMailer passes the value of config.action_mailer.mailtrap_settings, and only allowed parameters are accepted.

```APIDOC
## [Ruby] Mailtrap::ActionMailer::DeliveryMethod#initialize

### Description
Initializes a new delivery method instance with the provided settings. ActionMailer passes the value of `config.action_mailer.mailtrap_settings`, and only allowed parameters are accepted.

### Method
Ruby constructor

### Endpoint
`Mailtrap::ActionMailer::DeliveryMethod.new(settings)`

### Parameters
#### Constructor Parameters
- **settings** (Hash) - Required - Delivery settings. ActionMailer passes the value of `config.action_mailer.mailtrap_settings`. Keys accepted by the internal client are restricted to `ALLOWED_PARAMS` via `settings.slice(*ALLOWED_PARAMS)`.

### Request Example
ruby
Mailtrap::ActionMailer::DeliveryMethod.new(api_key: 'your-api-key', bulk: false)


### Response
#### Success Response
Returns a new `Mailtrap::ActionMailer::DeliveryMethod` instance.

#### Response Example
ruby
#<Mailtrap::ActionMailer::DeliveryMethod:0x... @settings={:api_key=>"your-api-key", :bulk=>false}>

```

--------------------------------

### Implementing a concrete API class

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/base_api.md

An example of including BaseAPI in a class, defining the base_path, and overriding helper methods like wrap_request and handle_response.

```ruby
class ProjectsAPI
  include BaseAPI
  self.supported_options = %i[name]
  self.response_class = Project

  def list
    base_list
  end

  def create(options)
    base_create(options)
  end

  private

  def base_path
    "/api/accounts/#{account_id}/projects"
  end

  def wrap_request(options)
    { project: options }     # POST/PATCH body envelope
  end

  def handle_response(response)
    build_entity(
      response.merge(inboxes: response[:inboxes]&.map { |i| build_entity(i, Mailtrap::Inbox) }),
      response_class
    )
  end
end
```

--------------------------------

### ContactFieldsAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-crud-apis.md

Example usage of ContactFieldsAPI: create a field with name, data_type, and merge_tag; update its name; list all fields; and delete the field. Demonstrates the typical workflow for managing contact fields.

```ruby
fields = Mailtrap::ContactFieldsAPI.new(account_id: 123)
field = fields.create(name: 'Birth date', data_type: 'date', merge_tag: 'birth_date')
fields.update(field.id, name: 'Birthday')
fields.list.each { |f| puts "#{f.merge_tag}: #{f.data_type}" }
fields.delete(field.id)
```

--------------------------------

### SandboxMessagesAPI get, delete, mark_as_read method signatures

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/sandbox-apis.md

Defines the get, delete, and mark_as_read methods. All return SandboxMessage; delete returns the deleted object. mark_as_read defaults is_read to true. Raises Mailtrap::Error subclasses.

```ruby
def get(message_id)                  # line 33
def delete(message_id)               # line 41
def mark_as_read(message_id, is_read: true)   # line 50
```

--------------------------------

### BillingAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/account-management-apis.md

Creates a BillingAPI instance with account_id 123, retrieves usage, and prints sending, testing, and billing details.

```ruby
usage = Mailtrap::BillingAPI.new(account_id: 123).usage
puts "sending: #{usage.sending.inspect}, testing: #{usage.testing.inspect}, billing: #{usage.billing.inspect}"
```

--------------------------------

### GET /api/inbound/folders

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/endpoints.md

Retrieves a list of inbound folders.

```APIDOC
## GET /api/inbound/folders

### Description
Retrieves a list of inbound folders.

### Method
GET

### Endpoint
/api/inbound/folders

### Response
#### Success Response (200)
- **Array<InboundFolder>** - List of inbound folders

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Folder"
  }
]
```
```

--------------------------------

### Define WebhooksAPI methods (list, get, create, update, delete)

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-sending-apis.md

Shows the method signatures for the WebhooksAPI class: list, get, create, update, and delete. The create method accepts options including url, webhook_type, active, payload_format, sending_stream, event_types, domain_id, and inbound_inbox_id. Update only allows url, active, payload_format, event_types, and inbound_inbox_id.

```ruby
def list   # line 18

```

```ruby
def get(webhook_id)        # line 27
def create(options)        # line 50
def update(webhook_id, options)  # line 67  (allowed: url, active, payload_format, event_types, inbound_inbox_id)
def delete(webhook_id)     # line 75

```

--------------------------------

### get

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/email-marketing-apis.md

Retrieves a specific email template by its ID.

```APIDOC
## [GET] /api/accounts/{account_id}/email_templates/{template_id}

### Description
Retrieves a specific email template by its ID.

### Method
GET

### Endpoint
/api/accounts/{account_id}/email_templates/{template_id}

### Parameters
#### Path Parameters
- **account_id** (integer) - Required - The account ID.
- **template_id** (integer) - Required - The template ID.

### Response
#### Success Response (200)
- **email_template** (EmailTemplate) - The requested email template.

#### Response Example
```json
{
  "id": 1,
  "name": "Welcome",
  "subject": "Welcome!",
  "category": "Onboarding",
  "body_html": "<h1>Hi</h1>",
  "body_text": "Hi"
}
```
```

--------------------------------

### GET /api/inbound/folders/{folder_id}

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/endpoints.md

Retrieves a specific inbound folder by its ID.

```APIDOC
## GET /api/inbound/folders/{folder_id}

### Description
Retrieves a specific inbound folder by its ID.

### Method
GET

### Endpoint
/api/inbound/folders/{folder_id}

### Parameters
#### Path Parameters
- **folder_id** (integer) - Required - The ID of the folder to retrieve.

### Response
#### Success Response (200)
- **InboundFolder** - The requested inbound folder.

#### Response Example
```json
{
  "id": 1,
  "name": "Folder"
}
```
```

--------------------------------

### Mailtrap::Mail::Base#initialize

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/mail.md

Creates a new Mailtrap::Mail::Base instance with optional parameters for email content, recipients, attachments, and template variables.

```APIDOC
## Mailtrap::Mail::Base#initialize

### Description
Creates a new Mailtrap::Mail::Base instance. All parameters are optional and can be set via the constructor or via attribute accessors.

### Method
Constructor

### Signature
```ruby
def initialize(
  from: nil, to: [], reply_to: nil, cc: [], bcc: [],
  subject: nil, text: nil, html: nil, attachments: [],
  headers: {}, custom_variables: {}, category: nil,
  template_uuid: nil, template_variables: {}
)
```

### Parameters
- `from` (Hash) - Optional - Sender email address.
- `to` (Array<Hash>) - Optional - Recipient email addresses.
- `reply_to` (Hash) - Optional - Reply-to email address.
- `cc` (Array<Hash>) - Optional - CC recipients.
- `bcc` (Array<Hash>) - Optional - BCC recipients.
- `subject` (String) - Optional - Email subject.
- `text` (String) - Optional - Plain text body.
- `html` (String) - Optional - HTML body.
- `attachments` (Array) - Optional - Attachments; converted to `Mailtrap::Attachment` objects.
- `headers` (Hash) - Optional - Custom headers.
- `custom_variables` (Hash) - Optional - Custom variables.
- `category` (String) - Optional - Email category.
- `template_uuid` (String) - Optional - Template UUID.
- `template_variables` (Hash) - Optional - Template variables.

### Example
```ruby
mail = Mailtrap::Mail::Base.new(
  to: [{ email: 'jane.doe@email.com' }],
  template_variables: { user_name: 'Jane Doe' }
)
```
```

--------------------------------

### GET /api/accounts/{id}/stats

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/endpoints.md

Retrieves sending statistics for an account.

```APIDOC
## GET /api/accounts/{id}/stats

### Description
Retrieves sending statistics for an account.

### Method
GET

### Endpoint
/api/accounts/{id}/stats

### Parameters
#### Path Parameters
- **id** (string) - Required - The account ID.

#### Query Parameters
- **start_date** (string) - Optional - Start date for the stats.
- **end_date** (string) - Optional - End date for the stats.
- **sending_domain_ids[]** (array) - Optional - Filter by sending domain IDs.
- **sending_streams[]** (array) - Optional - Filter by sending streams.
- **categories[]** (array) - Optional - Filter by categories.
- **email_service_providers[]** (array) - Optional - Filter by email service providers.

### Response
#### Success Response (200)
- **data** (SendingStats) - The sending statistics.

#### Response Example
{
  "data": {
    "total": 0,
    "sent": 0,
    "delivered": 0,
    "failed": 0
  }
}
```

--------------------------------

### ApiTokensAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/token-permission-apis.md

Demonstrates creating, resetting, and deleting an API token. The created token value is printed once and should be stored securely. The reset call with expires_at: nil creates a never-expiring token.

```ruby
tokens = Mailtrap::ApiTokensAPI.new(account_id: 123)

created = tokens.create(
  name: 'CI deploy token',
  expires_at: '2027-01-01T00:00:00Z',
  resources: [{ resource_type: 'account', resource_id: 123, access_level: 'read' }]
)
puts created.token   # store this once!

rotated = tokens.reset(created.id, expires_at: nil)   # never expires
tokens.delete(rotated.id)
```

--------------------------------

### GET /api/tracking_opt_outs

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/endpoints.md

Retrieves a list of tracking opt-outs with optional filters.

```APIDOC
## GET /api/tracking_opt_outs

### Description
Retrieves a list of tracking opt-outs with optional filters.

### Method
GET

### Endpoint
/api/tracking_opt_outs

### Parameters
#### Query Parameters
- **email** (string) - Optional - Filter by email address.
- **start_time** (string) - Optional - Start time filter.
- **end_time** (string) - Optional - End time filter.
- **last_id** (string) - Optional - Last ID for pagination.

### Response
#### Success Response (200)
- **data** (Array<TrackingOptOut>) - The list of tracking opt-outs.
- **last_id** (string) - The last ID for pagination.

#### Response Example
{
  "data": [
    {
      "id": "string",
      "email": "string"
    }
  ],
  "last_id": "string"
}
```

--------------------------------

### SubAccountsAPI#initialize

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/account-management-apis.md

Constructor for SubAccountsAPI. Requires an organization_id. Raises ArgumentError if organization_id is nil.

```APIDOC
## SubAccountsAPI#initialize

### Description
Constructor for SubAccountsAPI. Requires an organization_id.

### Method
Constructor

### Signature
```ruby
def initialize(organization_id, client = Mailtrap::Client.new)
```

### Parameters
- **organization_id** (Integer) - Required - Organization ID; raises ArgumentError 'organization_id is required' if nil
- **client** (Mailtrap::Client) - Optional - Default: `Mailtrap::Client.new` - Transport

### Example
```ruby
sub = Mailtrap::SubAccountsAPI.new(organization_id: 5)
```
```

--------------------------------

### GET /api/accounts/{id}/contacts/fields

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/endpoints.md

Retrieves a list of contact fields.

```APIDOC
## GET /api/accounts/{id}/contacts/fields

### Description
Retrieves a list of contact fields.

### Method
GET

### Endpoint
/api/accounts/{id}/contacts/fields

### Parameters
#### Path Parameters
- **id** (string) - Required - The account ID.

### Response
#### Success Response (200)
- **Array<ContactField>** - An array of contact field objects.

#### Response Example
```json
[
  {
    "id": "string",
    "name": "string",
    "data_type": "string",
    "merge_tag": "string"
  }
]
```
```

--------------------------------

### GET /api/accounts/{id}/contacts/lists

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/endpoints.md

Retrieves a list of contact lists.

```APIDOC
## GET /api/accounts/{id}/contacts/lists

### Description
Retrieves a list of contact lists.

### Method
GET

### Endpoint
/api/accounts/{id}/contacts/lists

### Parameters
#### Path Parameters
- **id** (string) - Required - The account ID.

#### Query Parameters
- **search** (string) - Optional - Search query.

### Response
#### Success Response (200)
- **Array<ContactList>** - An array of contact list objects.

#### Response Example
```json
[
  {
    "id": "string",
    "name": "string"
  }
]
```
```

--------------------------------

### PermissionsAPI usage example

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/token-permission-apis.md

Demonstrates bulk updating permissions and recursively walking the resource tree. The bulk_update call removes a permission with _destroy: true. The walk method prints each node's type, name, and access level.

```ruby
perms = Mailtrap::PermissionsAPI.new(account_id: 123)

perms.bulk_update(55, [
  { resource_id: 9, resource_type: 'project', access_level: 'editor' },
  { resource_id: 3, resource_type: 'inbox', _destroy: true }   # remove
])

def walk(nodes, depth = 0)
  nodes.each do |node|
    puts("#{'  ' * depth}#{node.type} #{node.name} (level=#{node.access_level})")
    walk(node.resources, depth + 1)
  end
end
walk(perms.resources)
```

--------------------------------

### ContactsAPI get method

Source: https://github.com/mailtrap/mailtrap-ruby/blob/main/_autodocs/api-reference/contacts-crud-apis.md

Retrieves a contact by its UUID or email address.

```ruby
def get(contact_id)   # line 17
```
Tokens:
Raw