Mailhub Ruby Library

The Mailhub Ruby library provides convenient access to the Mailhub APIs from Ruby.

Table of Contents

• Reference
• Usage
• Environments
• Errors
• Advanced
  • Retries
  • Timeouts
  • Additional Headers
  • Additional Query Parameters
• Contributing

Reference

A full reference for this library is available here.

Usage

Instantiate and use the client with the following:

require "mailhub"

client = Mailhub::MailhubClient.new(api_key: "<value>")

client.campaign.create_campaign

Environments

This SDK allows you to configure different custom URLs for API requests. You can specify your own custom URL.

Custom URL

require "Mailhub"

client = Mailhub::MailhubClient.new(
    base_url: "https://example.com"
)

Errors

Failed API calls will raise errors that can be rescued from granularly.

require "Mailhub"

client = Mailhub::MailhubClient.new(
    base_url: "https://example.com"
)

begin
    result = client.campaign.create_campaign
rescue Mailhub::Errors::TimeoutError
    puts "API didn't respond before our timeout elapsed"
rescue Mailhub::Errors::ServiceUnavailableError
    puts "API returned status 503, is probably overloaded, try again later"
rescue Mailhub::Errors::ServerError
    puts "API returned some other 5xx status, this is probably a bug"
rescue Mailhub::Errors::ResponseError => e
    puts "API returned an unexpected status other than 5xx: #{e.code} #{e.message}"
rescue Mailhub::Errors::ApiError => e
    puts "Some other error occurred when calling the API: #{e.message}"
end

Advanced

Retries

The SDK is instrumented with automatic retries. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Error)

The retryStatusCodes configuration controls which 5XX status codes are retried:

• legacy (default): Retries 408, 429, 500, 502, 503, 504, 521, 522, 524
• recommended: Retries 408, 429, 502, 503, 504 only (excludes 500 Internal Server Error to avoid retrying non-idempotent failures)

Use the max_retries option to configure this behavior.

require "Mailhub"

client = Mailhub::MailhubClient.new(
    base_url: "https://example.com",
    max_retries: 3  # Configure max retries (default is 2)
)

Timeouts

The SDK defaults to a 60 second timeout. Use the timeout option to configure this behavior.

require "Mailhub"

response = client.campaign.create_campaign(
    ...,
    timeout: 30  # 30 second timeout
)

Additional Headers

If you would like to send additional headers as part of the request, use the additional_headers request option.

require "Mailhub"

response = client.campaign.create_campaign(
    ...,
    request_options: {
        additional_headers: {
            "X-Custom-Header" => "custom-value"
        }
    }
)

Additional Query Parameters

If you would like to send additional query parameters as part of the request, use the additional_query_parameters request option.

require "Mailhub"

response = client.campaign.create_campaign(
    ...,
    request_options: {
        additional_query_parameters: {
            "custom_param" => "custom-value"
        }
    }
)

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!