mailblastr 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bace5e9375b668304c40339acea2334895be7f7af3221f628ad4f7fa21762752
+  data.tar.gz: a68a14501aab6cf50309f0bb0d938dad58a5b4a96b31cb09cb9b5285f63979eb
+SHA512:
+  metadata.gz: ac99877d9dc0970341b2c1b16e075dfb1f32832d6f10d6fbc220243ccd02a73597cbda5534f5918b5f28f577a2090b5becfa51f23d2e22e90f901446d76a3d1f
+  data.tar.gz: 7e0e7c62751f5042054e502964595e6ffbc6f732469dca2076bdb748031449efb0023bc5fbd1ae5d1901a4f2ce0aed999957dc82ea0b4b8d693c6416543d5225

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MailBlastr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,332 @@
+# mailblastr
+
+Official Ruby SDK for the [MailBlastr](https://www.mailblastr.com) email API — send transactional and marketing email from your own verified domain.
+
+Zero runtime dependencies: the gem uses only Ruby's standard library (`Net::HTTP`, `JSON`, `OpenSSL`).
+
+## Install
+
+```bash
+gem install mailblastr
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "mailblastr"
+```
+
+## Setup
+
+```ruby
+require "mailblastr"
+
+Mailblastr.api_key = "mb_xxxxxxxxx"
+
+# or
+Mailblastr.configure do |config|
+  config.api_key = ENV["MAILBLASTR_API_KEY"]
+  # config.base_url = "https://www.mailblastr.com/api" # override your API host
+end
+```
+
+## Usage
+
+```ruby
+sent = Mailblastr::Emails.send({
+  from: "Acme <hello@yourdomain.com>",
+  to: ["user@example.com"],
+  subject: "Hello from MailBlastr",
+  html: "<p>Your first email 🎉</p>"
+})
+puts sent["id"]
+```
+
+Params are plain hashes with snake_case keys, passed through as JSON. Successful calls return the parsed response (a Hash, or a raw String for binary downloads). Any non-2xx response raises `Mailblastr::Error`:
+
+```ruby
+begin
+  Mailblastr::Emails.send(params)
+rescue Mailblastr::Error => e
+  puts e.status_code # => 422
+  puts e.name        # => "validation_error"
+  puts e.message     # => human-readable explanation
+end
+```
+
+## Domain-first model
+
+MailBlastr is **domain-first**: each sending domain has its own pool of contacts. The same email address on two domains is two records with separate consent, so unsubscribes on one product never leak into another.
+
+That means `domain` (the sending domain, e.g. `"yourdomain.com"` — one of your verified domains) is **required** on:
+
+- `Contacts.create` / `Contacts.list` (the flat `/contacts` API — pass `audience_id:` to use the nested audience routes instead)
+- `Segments.create` / `Segments.list`
+- `Topics.create` / `Topics.list`
+- `Campaigns.create` (picks the contact pool the campaign targets; `from` may be a different verified domain)
+- `Automations.create` and `Events.send` (only automations belonging to that domain are triggered)
+
+## Emails
+
+```ruby
+Mailblastr::Emails.send({ from: from, to: to, subject: subject, html: html })
+Mailblastr::Emails.list({ limit: 20, after: cursor })   # cursor pagination
+Mailblastr::Emails.get(email_id)
+Mailblastr::Emails.list_attachments(email_id)
+Mailblastr::Emails.get_attachment(email_id, attachment_id)
+Mailblastr::Emails.update(email_id, { scheduled_at: "2026-08-01T09:00:00Z" }) # reschedule
+Mailblastr::Emails.cancel(email_id)
+
+# Batch send — up to 100 emails in one request
+Mailblastr::Batch.send([
+  { from: from, to: ["a@example.com"], subject: "Hi A", html: "<p>A</p>" },
+  { from: from, to: ["b@example.com"], subject: "Hi B", html: "<p>B</p>" }
+])
+
+# Attachments: hosted URL (path) or inline base64 (content)
+Mailblastr::Emails.send({
+  from: from, to: to, subject: "Your invoice", html: "<p>Attached.</p>",
+  attachments: [
+    { filename: "invoice.pdf", path: "https://yourdomain.com/invoices/invoice.pdf" },
+    { filename: "report.csv", content: base64_content, content_type: "text/csv" }
+  ]
+})
+```
+
+### Inbound email
+
+```ruby
+Mailblastr::Emails::Receiving.list
+Mailblastr::Emails::Receiving.get(id)
+Mailblastr::Emails::Receiving.list_attachments(id)
+Mailblastr::Emails::Receiving.get_attachment(id, attachment_id) # => raw bytes (String)
+Mailblastr::Emails::Receiving.raw(id)                           # => original RFC822 message
+Mailblastr::Emails::Receiving.forward(id, { from: "you@yourdomain.com", to: "team@you.com" })
+Mailblastr::Emails::Receiving.reply(id, { from: "you@yourdomain.com", html: "<p>Thanks!</p>" })
+Mailblastr::Emails::Receiving.delete(id)
+```
+
+## Domains
+
+```ruby
+Mailblastr::Domains.create({ name: "yourdomain.com" })
+Mailblastr::Domains.get(id)
+Mailblastr::Domains.list
+Mailblastr::Domains.update(id, { click_tracking: true })
+Mailblastr::Domains.verify(id)
+Mailblastr::Domains.delete(id)
+
+# Claim a domain verified in another account
+Mailblastr::Domains.claim({ name: "yourdomain.com" })
+Mailblastr::Domains.get_claim(id)
+Mailblastr::Domains.verify_claim(id)
+
+# One-click DNS setup
+Mailblastr::Domains.detect_dns(id)
+Mailblastr::Domains.apply_cloudflare_dns(id, { token: cf_token })
+Mailblastr::Domains.apply_godaddy_dns(id, { key: key, secret: secret })
+Mailblastr::Domains.apply_namecheap_dns(id, { apiUser: user, apiKey: key })
+```
+
+## Contacts (domain-first)
+
+```ruby
+Mailblastr::Contacts.create({ domain: "yourdomain.com", email: "user@example.com", first_name: "Ada" })
+Mailblastr::Contacts.list({ domain: "yourdomain.com" })
+Mailblastr::Contacts.get({ id: contact_id })                                # by id (exact) …
+Mailblastr::Contacts.get({ id: "user@example.com", domain: "yourdomain.com" }) # … or email + domain
+Mailblastr::Contacts.update({ id: contact_id, unsubscribed: true })
+Mailblastr::Contacts.delete({ id: contact_id })
+
+# Nested audience variants
+Mailblastr::Contacts.create({ audience_id: aud_id, email: "user@example.com" })
+Mailblastr::Contacts.list({ audience_id: aud_id, segment_id: seg_id })
+
+# Bulk import
+Mailblastr::Contacts.batch({ audience_id: aud_id, contacts: [{ email: "a@b.com" }], on_conflict: "skip" })
+Mailblastr::Contacts.import({ audience_id: aud_id, csv: "email,company\na@b.com,Acme" })
+
+# Segments & topics per contact
+Mailblastr::Contacts.add_to_segment(contact_id, segment_id)
+Mailblastr::Contacts.remove_from_segment(contact_id, segment_id)
+Mailblastr::Contacts.list_segments(contact_id)
+Mailblastr::Contacts.get_topics(contact_id)
+Mailblastr::Contacts.update_topics(contact_id, { topics: [{ id: topic_id, subscription: "opt_in" }] })
+
+# Custom contact properties ({{merge_tags}})
+Mailblastr::ContactProperties.create({ key: "plan", type: "string", fallback_value: "free" })
+```
+
+## Audiences
+
+```ruby
+Mailblastr::Audiences.create({ name: "Newsletter" })
+Mailblastr::Audiences.get(id)
+Mailblastr::Audiences.list
+Mailblastr::Audiences.update(id, { name: "Weekly newsletter" })
+Mailblastr::Audiences.delete(id)
+
+# Import from a link-shared Google Sheet
+Mailblastr::Audiences.import_sheet(id, { url: sheet_url, segment_name: "June leads" })
+```
+
+## Segments & Topics (domain-first)
+
+```ruby
+Mailblastr::Segments.create({ domain: "yourdomain.com", name: "VIP", filter: { status: "subscribed" } })
+Mailblastr::Segments.list({ domain: "yourdomain.com" })
+Mailblastr::Segments.get(id)
+Mailblastr::Segments.contacts(id) # preview who matches
+Mailblastr::Segments.update(id, { name: "VIP customers" })
+Mailblastr::Segments.delete(id)
+
+Mailblastr::Topics.create({ domain: "yourdomain.com", name: "Product updates", default_subscription: "opt_in" })
+Mailblastr::Topics.list({ domain: "yourdomain.com" })
+Mailblastr::Topics.update(id, { description: "New features" })
+Mailblastr::Topics.delete(id)
+```
+
+## Campaigns (domain-first)
+
+```ruby
+campaign = Mailblastr::Campaigns.create({
+  domain: "yourdomain.com", # REQUIRED — the contact pool this campaign targets
+  from: "Acme <hello@yourdomain.com>",
+  subject: "Big news",
+  html: "<p>Hello {{first_name}}</p>",
+  segment_id: seg_id # optional — subset instead of everyone
+})
+
+Mailblastr::Campaigns.send(campaign["id"])                                    # send now
+Mailblastr::Campaigns.send(campaign["id"], { scheduled_at: "2026-08-01T09:00:00Z" }) # or schedule
+Mailblastr::Campaigns.cancel(campaign["id"])
+Mailblastr::Campaigns.stats(campaign["id"])
+Mailblastr::Campaigns.ab(campaign["id"]) # A/B winner evaluation
+Mailblastr::Campaigns.get(campaign["id"])
+Mailblastr::Campaigns.list({ limit: 25 })
+Mailblastr::Campaigns.update(campaign["id"], { subject: "Bigger news" })
+Mailblastr::Campaigns.delete(campaign["id"])
+```
+
+## Templates
+
+```ruby
+tmpl = Mailblastr::Templates.create({ name: "Welcome", subject: "Welcome!", html: "<p>Hi {{first_name}}</p>" })
+Mailblastr::Templates.publish(tmpl["id"])
+Mailblastr::Templates.duplicate(tmpl["id"], { name: "Welcome v2" })
+Mailblastr::Templates.get(tmpl["id"])
+Mailblastr::Templates.list
+Mailblastr::Templates.update(tmpl["id"], { subject: "Welcome aboard!" })
+Mailblastr::Templates.delete(tmpl["id"])
+
+# Send with a template
+Mailblastr::Emails.send({ from: from, to: to, template_id: tmpl["id"], variables: { first_name: "Ada" } })
+```
+
+## Automations & Events (domain-first)
+
+```ruby
+automation = Mailblastr::Automations.create({
+  name: "Welcome series",
+  domain: "yourdomain.com", # REQUIRED
+  trigger: "contact.created"
+})
+
+Mailblastr::Automations.add_step(automation["id"], { type: "send_email", config: { template_id: tmpl_id } })
+Mailblastr::Automations.update(automation["id"], { status: "enabled" })
+
+# Fire a custom event — only yourdomain.com's automations are triggered
+Mailblastr::Events.send({
+  event: "signup.completed",
+  domain: "yourdomain.com", # REQUIRED
+  email: "user@example.com",
+  payload: { plan: "pro" }
+})
+
+# Event definitions
+Mailblastr::Events.create({ name: "signup.completed", schema: { plan: "string" } })
+Mailblastr::Events.list
+Mailblastr::Events.delete(event_id)
+
+# Inspect execution
+runs = Mailblastr::Automations.runs(automation["id"], { limit: 25 })
+Mailblastr::Automations.get_run(automation["id"], runs["data"].first["id"])
+Mailblastr::Automations.delete_step(automation["id"], step_id)
+Mailblastr::Automations.stop(automation["id"])
+Mailblastr::Automations.delete(automation["id"])
+```
+
+## Webhooks
+
+```ruby
+hook = Mailblastr::Webhooks.create({
+  endpoint: "https://yourapp.com/hooks/mailblastr",
+  events: ["email.delivered", "email.bounced", "contact.unsubscribed"]
+})
+hook["signing_secret"] # shown ONCE — store it
+
+Mailblastr::Webhooks.list
+Mailblastr::Webhooks.update(hook["id"], { status: "disabled" })
+Mailblastr::Webhooks.rotate(hook["id"]) # new secret returned once
+Mailblastr::Webhooks.test(hook["id"])
+Mailblastr::Webhooks.delete(hook["id"])
+```
+
+### Verifying deliveries
+
+`verify_signature` checks the Svix-style HMAC-SHA256 signature locally (no HTTP request). Pass the **exact raw request body** — re-serializing parsed JSON breaks the signature.
+
+```ruby
+result = Mailblastr::Webhooks.verify_signature(
+  request.raw_post,          # raw body string
+  {
+    "svix-id" => request.headers["svix-id"],
+    "svix-timestamp" => request.headers["svix-timestamp"],
+    "svix-signature" => request.headers["svix-signature"]
+  },
+  signing_secret             # the whsec_... secret from create/rotate
+)
+
+head :unauthorized unless result[:valid]
+# result => { valid: true } or { valid: false, reason: "no_match" | "timestamp_out_of_tolerance" | ... }
+```
+
+Pass `tolerance: 0` to skip the timestamp freshness check (default 300 seconds).
+
+## API keys, Logs & Polls
+
+```ruby
+Mailblastr::ApiKeys.create({ name: "CI", permission: "sending_access" })
+Mailblastr::ApiKeys.list
+Mailblastr::ApiKeys.delete(key_id)
+
+Mailblastr::Logs.list({ limit: 100, method: "POST", status: 429 })
+Mailblastr::Logs.get(log_id)
+
+Mailblastr::Polls.list
+Mailblastr::Polls.get(email_id) # aggregated answer breakdown
+```
+
+## Pagination
+
+`list` methods accept cursor pagination — `{ limit:, after:, before: }` — appended as a query string:
+
+```ruby
+Mailblastr::Campaigns.list({ limit: 25, after: "cursor_abc" })
+```
+
+## Idempotency
+
+Pass an idempotency key to safely retry a create (24h window):
+
+```ruby
+Mailblastr::Emails.send(payload, { idempotency_key: "order-123" })
+```
+
+## Documentation
+
+Full docs: <https://www.mailblastr.com/docs>
+
+## License
+
+MIT

data/lib/mailblastr/api_keys.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  module ApiKeys
+    class << self
+      # Create an API key — the full token is returned only once, here.
+      # POST /api-keys — params: { name:, permission: "full_access"|"sending_access", domain_id: }
+      def create(params)
+        Client.request(:post, "/api-keys", body: params)
+      end
+
+      # GET /api-keys
+      def list
+        Client.request(:get, "/api-keys")
+      end
+
+      # DELETE /api-keys/:id
+      def delete(api_key_id)
+        Client.request(:delete, "/api-keys/#{Client.path_escape(api_key_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/audiences.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  module Audiences
+    class << self
+      # POST /audiences — params: { name: "..." }
+      def create(params)
+        Client.request(:post, "/audiences", body: params)
+      end
+
+      # GET /audiences/:id
+      def get(audience_id)
+        Client.request(:get, "/audiences/#{Client.path_escape(audience_id)}")
+      end
+
+      # GET /audiences
+      def list(params = {})
+        Client.request(:get, "/audiences", query: Client.pagination(params))
+      end
+
+      # Rename an audience. PATCH /audiences/:id
+      def update(audience_id, params)
+        Client.request(:patch, "/audiences/#{Client.path_escape(audience_id)}", body: params)
+      end
+
+      # DELETE /audiences/:id
+      def delete(audience_id)
+        Client.request(:delete, "/audiences/#{Client.path_escape(audience_id)}")
+      end
+
+      # Import contacts from a link-shared Google Sheet; header columns become
+      # contact properties and rows land in a fresh segment.
+      # POST /audiences/:id/contacts/import-sheet — params: { url:, segment_name: }
+      def import_sheet(audience_id, params)
+        Client.request(:post, "/audiences/#{Client.path_escape(audience_id)}/contacts/import-sheet", body: params)
+      end
+    end
+  end
+end

data/lib/mailblastr/automations.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Automations are DOMAIN-FIRST: `domain` is required on create, and only
+  # Events.send calls naming the same domain trigger them.
+  module Automations
+    class << self
+      # POST /automations
+      #   Mailblastr::Automations.create({ name: "Welcome series", domain: "yourdomain.com",
+      #                                    trigger: "contact.created" })
+      def create(params)
+        Client.require_domain!(params, "Automations.create")
+        Client.request(:post, "/automations", body: params)
+      end
+
+      # GET /automations/:id
+      def get(automation_id)
+        Client.request(:get, "/automations/#{Client.path_escape(automation_id)}")
+      end
+
+      # GET /automations
+      def list(params = {})
+        Client.request(:get, "/automations", query: Client.pagination(params))
+      end
+
+      # PATCH /automations/:id — params: { name:, status: "enabled"|"disabled", ... }
+      def update(automation_id, params)
+        Client.request(:patch, "/automations/#{Client.path_escape(automation_id)}", body: params)
+      end
+
+      # Append a step. POST /automations/:id/steps — params: { type:, config:, key: }
+      def add_step(automation_id, params)
+        Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/steps", body: params)
+      end
+
+      # Delete a step. DELETE /automations/:id/steps/:step_id
+      def delete_step(automation_id, step_id)
+        Client.request(:delete, "/automations/#{Client.path_escape(automation_id)}/steps/#{Client.path_escape(step_id)}")
+      end
+
+      # List an automation's runs. GET /automations/:id/runs
+      def runs(automation_id, params = {})
+        Client.request(:get, "/automations/#{Client.path_escape(automation_id)}/runs", query: Client.pagination(params))
+      end
+
+      # Retrieve a single run with its step trace. GET /automations/:id/runs/:run_id
+      def get_run(automation_id, run_id)
+        Client.request(:get, "/automations/#{Client.path_escape(automation_id)}/runs/#{Client.path_escape(run_id)}")
+      end
+
+      # Stop an automation — no new runs; in-progress runs finish. POST /automations/:id/stop
+      def stop(automation_id)
+        Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/stop")
+      end
+
+      # DELETE /automations/:id
+      def delete(automation_id)
+        Client.request(:delete, "/automations/#{Client.path_escape(automation_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/campaigns.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Campaigns are DOMAIN-FIRST: `domain` (required on create) picks the
+  # contact pool the campaign targets; `from` may be any verified domain.
+  module Campaigns
+    class << self
+      # POST /campaigns
+      #   Mailblastr::Campaigns.create({ domain: "yourdomain.com", from: "you@yourdomain.com",
+      #                                  subject: "Hello", html: "<p>Hi</p>", segment_id: "seg_1" })
+      def create(params)
+        Client.require_domain!(params, "Campaigns.create")
+        Client.request(:post, "/campaigns", body: params)
+      end
+
+      # GET /campaigns/:id
+      def get(campaign_id)
+        Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}")
+      end
+
+      # GET /campaigns
+      def list(params = {})
+        Client.request(:get, "/campaigns", query: Client.pagination(params))
+      end
+
+      # PATCH /campaigns/:id
+      def update(campaign_id, params)
+        Client.request(:patch, "/campaigns/#{Client.path_escape(campaign_id)}", body: params)
+      end
+
+      # Send now, or schedule with { scheduled_at: "..." }. POST /campaigns/:id/send
+      def send(campaign_id, params = {})
+        Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/send", body: params)
+      end
+
+      # Cancel a scheduled campaign (returns it to draft). POST /campaigns/:id/cancel
+      def cancel(campaign_id)
+        Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/cancel")
+      end
+
+      # Per-campaign analytics (counts, engagement rates, top links). GET /campaigns/:id/stats
+      def stats(campaign_id)
+        Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/stats")
+      end
+
+      # A/B winner evaluation for an A/B campaign. GET /campaigns/:id/ab
+      def ab(campaign_id)
+        Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/ab")
+      end
+
+      # DELETE /campaigns/:id
+      def delete(campaign_id)
+        Client.request(:delete, "/campaigns/#{Client.path_escape(campaign_id)}")
+      end
+    end
+  end
+end