norbelys

Norbelys - the Ruby gem for the Norbelys API

The Norbelys API is a single, predictable REST surface for cold email and outreach — people, senders, programs, and sending all live behind the five patterns below. Developer-first and AI-first: every name is either already invented (Schema.org) or obvious.

Authentication

Every request authenticates with an org-scoped API key. Create one in Settings → API keys and send it as a bearer token:

GET https://api.norbelys.com/v1/people
Authorization: Bearer ak_live_…

Interactive agents may instead use OAuth 2.1 (see /auth.md and the /.well-known/oauth-protected-resource metadata).

Conventions

  • Base URL — https://api.norbelys.com/v1.
  • JSON in, JSON out. Timestamps are ISO-8601 in UTC.
  • Cursor pagination. List endpoints take limit + cursor and return { data, hasMore, nextCursor } (offset-paged tables add page + total).
  • Expansions. Detail GETs take an expand[] query param to inline related data (e.g. GET /people/{id}?expand[]=timeline) instead of extra calls.
  • Soft deletes. Anything that has been used is archived, never hard-deleted — DELETE archives the resource and returns it.

Errors

Failures return the same envelope on every 4xx/5xx, with the matching HTTP status:

{ \"error\": { \"type\": \"invalid_request\", \"code\": \"invalid_param\",
            \"message\": \"…\", \"hint\": \"…\", \"doc_url\": \"…\" } }

type is a broad, machine-routable category derived from the status; code is the stable machine contract you branch on (never the human message). See the ApiError schema.

Idempotency

Every POST accepts an optional Idempotency-Key header. Reuse the same key to replay the original result for 24h instead of re-executing — so a retried create can never double-charge or duplicate a record.

Rate limits & versioning

Abuse control is enforced at the edge; responses advertise the policy via the RateLimit-Policy header, and a 429 carries Retry-After. The API is versioned in the URL path (/v1). Breaking changes ship under a new version; a retiring surface is announced with Deprecation + Sunset response headers at least 90 days ahead.

This SDK is automatically generated by the OpenAPI Generator project:

  • API version: 0.0.1
  • Package version: 0.1.0
  • Generator version: 7.10.0
  • Build package: org.openapitools.codegen.languages.RubyClientCodegen

Installation

Build a gem

To build the Ruby code into a gem:

gem build norbelys.gemspec

Then either install the gem locally:

gem install ./norbelys-0.1.0.gem

(for development, run gem install --dev ./norbelys-0.1.0.gem to install the development dependencies)

or publish the gem to a gem hosting service, e.g. RubyGems.

Finally add this to the Gemfile:

gem 'norbelys', '~> 0.1.0'

Install from Git

If the Ruby gem is hosted at a git repository: https://github.com/norbelys-com/sdk-ruby, then add the following in the Gemfile:

gem 'norbelys', :git => 'https://github.com/norbelys-com/sdk-ruby.git'

Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'norbelys'

# Setup authorization
Norbelys.configure do |config|
  # Configure Bearer authorization: bearerAuth
  config.access_token = 'YOUR_BEARER_TOKEN'
  # Configure a proc to get access tokens in lieu of the static access_token configuration
  config.access_token_getter = -> { 'YOUR TOKEN GETTER PROC' } 
end

api_instance = Norbelys::AnalyticsApi.new
analytics_query = Norbelys::AnalyticsQuery.new({query: Norbelys::AnalyticsQueryName::ACTIVITY_FEED}) # AnalyticsQuery | 
opts = {
  idempotency_key: 'idempotency_key_example' # String | Opt-in idempotency for a safely retried write: reuse the same key to replay the original result for 24h instead of re-executing. Recommended on every POST.
}

begin
  #Run an analytics query
  result = api_instance.analytics_query(analytics_query, opts)
  p result
rescue Norbelys::ApiError => e
  puts "Exception when calling AnalyticsApi->analytics_query: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://api.norbelys.com/v1

Class Method HTTP request Description
Norbelys::AnalyticsApi analytics_query POST /analytics/query Run an analytics query
Norbelys::DomainsApi domains_archive DELETE /domains/id Archive a domain
Norbelys::DomainsApi domains_create POST /domains Create a domain
Norbelys::DomainsApi domains_find GET /domains/id Get a domain
Norbelys::DomainsApi domains_list GET /domains List domains
Norbelys::DomainsApi domains_restore POST /domains/id/restore Restore an archived domain
Norbelys::DomainsApi domains_share POST /domains/id/share Share the DMARC report
Norbelys::DomainsApi domains_update PATCH /domains/id Update a domain
Norbelys::FieldsApi fields_archive DELETE /fields/id Delete a field
Norbelys::FieldsApi fields_create POST /fields Create a custom field
Norbelys::FieldsApi fields_list GET /fields List custom fields
Norbelys::FieldsApi fields_update PATCH /fields/id Update a field
Norbelys::FilesApi files_create POST /files Upload a public file
Norbelys::GroupsApi groups_archive DELETE /groups/id Delete a group
Norbelys::GroupsApi groups_create POST /groups Create a group
Norbelys::GroupsApi groups_find GET /groups/id Get a group
Norbelys::GroupsApi groups_list GET /groups List groups
Norbelys::GroupsApi groups_members_add POST /groups/id/members Add people to a group
Norbelys::GroupsApi groups_members_remove DELETE /groups/id/members/relId Remove a person from a group
Norbelys::GroupsApi groups_update PATCH /groups/id Update a group
Norbelys::IntegrationsApi integrations_connect POST /integrations/connect Connect an integration
Norbelys::IntegrationsApi integrations_find GET /integrations/id Get an integration
Norbelys::IntegrationsApi integrations_list GET /integrations List integrations
Norbelys::IntegrationsApi integrations_options GET /integrations/id/options List an integration's config options
Norbelys::IntegrationsApi integrations_remove DELETE /integrations/id Disconnect an integration
Norbelys::IntegrationsApi integrations_sync POST /integrations/id/sync Sync an integration now
Norbelys::IntegrationsApi integrations_update PATCH /integrations/id Update an integration
Norbelys::MessagesApi messages_attachment GET /messages/id/attachments/attachmentId Download a message attachment
Norbelys::MessagesApi messages_attachments GET /messages/id/attachments List a message's attachments
Norbelys::MessagesApi messages_create POST /messages Send a message
Norbelys::MessagesApi messages_find GET /messages/id Get a message
Norbelys::MessagesApi messages_list GET /messages List messages
Norbelys::MessagesApi messages_source GET /messages/id/source Get a sent message's source
Norbelys::MessagesApi messages_update PATCH /messages/id Triage an inbound message
Norbelys::OrganizationApi organization_features GET /organization/features Get the organization's feature flags
Norbelys::OrganizationApi organization_find GET /organization Get the organization
Norbelys::OrganizationApi organization_pulse GET /organization/pulse Get the workspace pulse
Norbelys::OrganizationApi organization_update PATCH /organization Update the organization
Norbelys::OrganizationApi organization_usage GET /organization/usage Get the organization's plan usage
Norbelys::PeopleApi people_archive DELETE /people/id Archive a person
Norbelys::PeopleApi people_audience_summary GET /people/audience-summary Get audience summary
Norbelys::PeopleApi people_bulk_create POST /people/bulk Bulk create people (verifies + suppresses in the background; optional group / campaign)
Norbelys::PeopleApi people_create POST /people Create a person
Norbelys::PeopleApi people_erase POST /people/id/erase Erase a person (GDPR)
Norbelys::PeopleApi people_find GET /people/id Get a person
Norbelys::PeopleApi people_get_bulk GET /people/bulk/id Get a bulk import's verify stats (sendable / suppressed / pending)
Norbelys::PeopleApi people_list GET /people List people
Norbelys::PeopleApi people_update PATCH /people/id Update a person
Norbelys::ProgramsApi programs_archive DELETE /programs/id Archive a program
Norbelys::ProgramsApi programs_audience_list GET /programs/id/audience List a program's audience sources
Norbelys::ProgramsApi programs_create POST /programs Create a program
Norbelys::ProgramsApi programs_enroll POST /programs/id/enroll Enroll people into a program
Norbelys::ProgramsApi programs_enrollments_find GET /programs/programId/enrollments/id Get an enrollment
Norbelys::ProgramsApi programs_enrollments_list GET /programs/programId/enrollments List a program's leads
Norbelys::ProgramsApi programs_find GET /programs/id Get a program
Norbelys::ProgramsApi programs_launch POST /programs/id/launch Launch a program
Norbelys::ProgramsApi programs_list GET /programs List programs
Norbelys::ProgramsApi programs_pause POST /programs/id/pause Pause a program's sending
Norbelys::ProgramsApi programs_restore POST /programs/id/restore Restore an archived program
Norbelys::ProgramsApi programs_resume POST /programs/id/resume Resume a paused program
Norbelys::ProgramsApi programs_senders_add POST /programs/id/senders Attach a sender to a program
Norbelys::ProgramsApi programs_senders_list GET /programs/id/senders List a program's senders
Norbelys::ProgramsApi programs_senders_remove DELETE /programs/id/senders/relId Detach a sender from a program
Norbelys::ProgramsApi programs_share POST /programs/id/share Share the campaign report
Norbelys::ProgramsApi programs_update PATCH /programs/id Update a program
Norbelys::SegmentsApi segments_archive DELETE /segments/id Delete a segment
Norbelys::SegmentsApi segments_create POST /segments Create a segment
Norbelys::SegmentsApi segments_find GET /segments/id Get a segment
Norbelys::SegmentsApi segments_list GET /segments List segments
Norbelys::SegmentsApi segments_update PATCH /segments/id Update a segment
Norbelys::SendersApi senders_bulk POST /senders/bulk Bulk-update senders
Norbelys::SendersApi senders_create POST /senders Connect a sender
Norbelys::SendersApi senders_find GET /senders/id Get a sender
Norbelys::SendersApi senders_list GET /senders List senders
Norbelys::SendersApi senders_remove DELETE /senders/id Delete or archive a sender
Norbelys::SendersApi senders_restore POST /senders/id/restore Restore an archived sender
Norbelys::SendersApi senders_update PATCH /senders/id Update a sender
Norbelys::SuppressionsApi suppressions_archive DELETE /suppressions/id Delete a suppression
Norbelys::SuppressionsApi suppressions_bulk POST /suppressions/bulk Bulk-suppress addresses
Norbelys::SuppressionsApi suppressions_create POST /suppressions Suppress an address or domain
Norbelys::SuppressionsApi suppressions_find GET /suppressions/id Get a suppression
Norbelys::SuppressionsApi suppressions_list GET /suppressions List suppressions
Norbelys::VerifyApi verify_email POST /verify Verify an email address

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

bearerAuth

  • Type: Bearer authentication