API reference

Request body · application/json

• titlestring

  Notification title. Required to send (400 title_required). Supports merge tags such as {name|there}.

• bodystring

  Message text. Supports merge tags.

• urlstring

  Page opened on click. Left out, your Default link is used; your UTM tags are added. Supports merge tags.

• iconstring

  Small image (URL). Left out, your default notification logo is used.

• imagestring

  Large picture (URL). Shown mainly by Chrome and Edge on Windows and Android.

• badgestring

  Small one-colour icon (URL of a PNG with a transparent background, about 96×96 px) for the Android status bar.

• actionsarray of Action

  Up to 2 buttons.

  Range: at most 2.

• actions[].actionstring

  Button id (defaults to btn1 / btn2).

• actions[].titlestringrequired

  Button text (required).

• actions[].urlstring

  Opened when the button is clicked; kept only when it is an http(s) link.

• requireInteractionboolean

  Keep the notification on screen until the person clicks or closes it (Chrome and Edge on computers).

• tagstring

  A label: a new notification with the same tag replaces one still showing.

• externalIdstring

  Send to one of your own users: the user id the browser SDK linked (externalId in init(), or identify()). Exact match, case matters.

• externalIdsarray of string

  The same for a list. Used instead of externalId when both are sent. All empty: 400 external_ids_empty (never everyone).

• transactionalboolean

  A message a person is waiting for: goes out even during quiet hours, skips the frequency cap, never listed in the public inbox.

• segmentIdstring (uuid)

  Target a saved segment. Not this website's: 400 segment_not_found.

• filtersFilters

  The segment filter format, shared by segments, inline send filters / excludeFilters, schedules and the audience list.

• filters.matchstring

  all = every rule must match (default), any = at least one.

  One of: all, any. Default "all".

• filters.rulesarray of Rule

  The rules.

• rules[].fieldstringrequired

  country (2-letter upper-case code from the visitor's IP), language, url (the subscriber's last page), external_id (or externalId), or tag:KEY for one of your tags. An unknown field matches nobody.

• rules[].opstring

  eq (default; also used for an unknown op), neq, contains (case-insensitive), in (value is a list), exists, not_exists. For a tag, neq also matches subscribers without that tag.

  One of: eq, neq, contains, in, exists, not_exists. Default "eq".

• rules[].valuestring or array of string

  Compared as text, exactly: eq, neq and in are case-sensitive (write country codes in upper case). Not needed for exists / not_exists.

• topicIdstring

  Only subscribers of this topic: its id or its slug (any case). Unknown: 400 unknown_topic.

• excludeSegmentIdstring (uuid)

  Leave this segment out. Unknown: 400 segment_not_found.

• excludeFiltersFilters

  The segment filter format, shared by segments, inline send filters / excludeFilters, schedules and the audience list.

• excludeFilters.matchstring

  all = every rule must match (default), any = at least one.

  One of: all, any. Default "all".

• excludeFilters.rulesarray of Rule

  The rules.

• rules[].fieldstringrequired

  country (2-letter upper-case code from the visitor's IP), language, url (the subscriber's last page), external_id (or externalId), or tag:KEY for one of your tags. An unknown field matches nobody.

• rules[].opstring

  eq (default; also used for an unknown op), neq, contains (case-insensitive), in (value is a list), exists, not_exists. For a tag, neq also matches subscribers without that tag.

  One of: eq, neq, contains, in, exists, not_exists. Default "eq".

• rules[].valuestring or array of string

  Compared as text, exactly: eq, neq and in are case-sensitive (write country codes in upper case). Not needed for exists / not_exists.

• sendAtstring (date-time)

  ISO 8601 time to schedule the send. In the past, or unreadable: sends now.

• perTimezoneboolean

  Deliver at localTime in each subscriber's time zone (sendAt is ignored).

• localTimestring

  "H:MM" or "HH:MM", with perTimezone.

• smartTimeboolean

  Deliver at each subscriber's most-active hour (sendAt is ignored).

• ttlinteger

  Seconds the push service keeps trying an offline device. Default 24 hours, at most 28 days (2419200).

  Range: 1–2419200.

• translationsmap of object

  Per-language copy keyed by two-letter language: { "es": { "title", "body" } }.

• translations.{key}.titlestring
• translations.{key}.bodystring
• abobject

  A/B test: each browser gets version A (the main fields) or B. Ignored unless b has at least one field.

• ab.bobjectrequired

  Version B; fields left out come from A.

• b.titlestring
• b.bodystring
• b.urlstring
• b.imagestring
• abTestobject

  Auto-winner, together with ab.

• abTest.autoWinnerboolean

  Send both versions to a test group, then the winner to the rest.

• abTest.testPercentinteger

  Test group size, 1–90 (default 20).

  Default 20. Range: 1–90.

• abTest.afterHoursinteger

  Hours before the winner goes out, 1–168 (default 4).

  Default 4. Range: 1–168.

• draftboolean

  true saves a draft instead of sending (201). The title may then be empty and nothing is checked yet.

Responses

• 201Draft saved (draft: true).
  Response fields

  • oktruerequired
  • notificationIdstring (uuid)required
  • status"draft"required
• 202Accepted.
  Response fields

  • oktruerequired
  • notificationIdstring (uuid)required

    Keep it: the send appears under this id in reports and webhooks, and it is how you cancel it.

  • statusstringrequired

    queued (sending starts now), scheduled (a future sendAt, or held until your quiet hours end) or held_for_review (a new account's first large broadcast; you can cancel it meanwhile).

    One of: queued, scheduled, held_for_review.

  • messagestring

    Only with held_for_review: what happens next.

• 400Bad request

  invalid_jsontitle_requiredunknown_fieldexternal_ids_emptyunknown_topicsegment_not_found

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  email_not_verifiedaccount_suspendedinsufficient_scope

• 409Conflict

  too_many_drafts

• 413Too large

  draft_too_largepayload_too_large

• 429Too many requests

  rate_limitedsend_limit_reached

Example

curl -X POST https://relaybell.com/api/v1/notifications \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "title": "Flash sale 🔥",
    "body": "30% off ends tonight — {name|there}!",
    "url": "https://shop.example/sale"
  }'

curl -X POST https://relaybell.com/api/v1/notifications \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "transactional": true,
    "title": "Your order has shipped",
    "body": "Order #1042 is on its way.",
    "url": "https://shop.example/orders/1042"
  }'

Query parameters

• fromstring (date)

  First day (YYYY-MM-DD, in tz) a notification was made on.

• tostring (date)

  Last day (YYYY-MM-DD, included).

• statusstring

  One or more of draft, scheduled, queued, held_for_review, sending, sent, failed, canceled, separated by commas.

• qstring

  Searches titles and texts, in any case.

• tzstring

  IANA time zone for from / to (default: the website's).

• limitinteger

  Items per page, 1–100 (default 25).

  Default 25.

• cursorstring

  The nextCursor from the previous page (send the same filters again). Anything else answers 400 invalid_cursor.

Responses

• 200A page of notifications.
  Response fields

  • itemsarray of NotificationListItemrequired
  • items[].idstring (uuid)required
  • items[].titlestringrequired
  • items[].bodystring or null
  • items[].statusstringrequired

    draft, scheduled, queued, held_for_review, sending, sent, failed (reason in error) or canceled.

    One of: draft, scheduled, queued, held_for_review, sending, sent, failed, canceled.

  • items[].created_atstring (date-time)required
  • items[].scheduled_atstring (date-time) or null

    When a scheduled send goes (or went) out; null for one that started straight away.

  • items[].recipientsintegerrequired

    Browsers targeted.

  • items[].sentintegerrequired

    Pushes the push services accepted.

  • items[].deliveredintegerrequired

    Pushes a device confirmed it showed.

  • items[].failedinteger

    Pushes that failed.

  • items[].prunedinteger

    Expired subscriptions found and removed during the send.

  • items[].clickedintegerrequired
  • items[].ctrnumberrequired

    clicked ÷ sent, as a percentage with one decimal.

  • items[].conversionsinteger
  • items[].revenuenumber
  • items[].abboolean

    Whether it was an A/B test.

  • items[].targetSummarystring

    Who it went to, in words: "All subscribers", a segment's name, "Topic: News", "Specific users", …

  • items[].automationboolean

    Whether an automation, a journey or a product alert made it.

  • items[].errorstring or null

    Why a failed send never went out (email_not_verified, suspended, segment_missing, review_rejected, dispatch_error), else null.

  • nextCursorstring or nullrequired

    Send as cursor (with the same filters) for the next page; null on the last page.

• 400Bad request

  invalid_statusinvalid_rangeinvalid_tzinvalid_cursor

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/notifications?status=sent&limit=25" \
  -H "Authorization: Bearer rb_live_xxxxx"

Query parameters

• fromstring (date)

  First day (YYYY-MM-DD).

• tostring (date)

  Last day (YYYY-MM-DD, included).

• statusstring

  Comma-separated statuses.

• qstring

  Search in titles and texts.

• tzstring

  IANA time zone for the days.

Responses

• 200The CSV file.text/csv
• 400Bad request

  invalid_statusinvalid_rangeinvalid_tz

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/notifications/export.csv" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The notification's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Responses

• 200The notification and its report.
  Response fields

  • notificationobjectrequired
  • notification.idstring (uuid)required
  • notification.titlestringrequired
  • notification.bodystring or null
  • notification.urlstring or null
  • notification.iconstring or null
  • notification.imagestring or null
  • notification.badgestring or null
  • notification.actionsarray of Action or null
  • notification.require_interactionboolean
  • notification.tagstring or null
  • notification.statusstringrequired

    draft, scheduled, queued, held_for_review, sending, sent, failed (reason in error) or canceled.

    One of: draft, scheduled, queued, held_for_review, sending, sent, failed, canceled.

  • notification.created_atstring (date-time)required
  • notification.scheduled_atstring (date-time) or null
  • notification.targetobject or null

    How the people were chosen ({ segmentId | filters, topicId, excludeSegmentId | excludeFilters, … }); null = everyone.

  • notification.targetSummarystring
  • notification.automationboolean
  • notification.automation_idstring (uuid) or null
  • notification.transactionalboolean
  • notification.abobject or null
  • notification.ab_testobject or null
  • notification.translationsobject or null
  • notification.ttlinteger or null
  • notification.per_timezoneboolean
  • notification.local_timestring or null

    "HH:MM", "smart", or null.

  • notification.statsobject or null
  • notification.errorstring or null
  • notification.recipientsinteger
  • notification.processedinteger
  • notification.sentinteger
  • notification.deliveredinteger
  • notification.failedinteger
  • notification.prunedinteger
  • notification.clickedinteger
  • notification.ctrnumber
  • notification.conversionsinteger
  • notification.revenuenumber
  • funnelobjectrequired
  • funnel.recipientsinteger
  • funnel.sentinteger
  • funnel.deliveredinteger
  • funnel.clickedinteger
  • funnel.convertedinteger
  • funnel.failedinteger
  • funnel.expiredinteger
  • devicesarray of objectrequired

    sent and clicked by device type (empty once data retention removed the send's event log).

  • devices[].devicestring
  • devices[].sentinteger
  • devices[].clickedinteger
  • variantsarray of objectrequired

    For an A/B send, versions a and b; otherwise empty.

  • variants[].variantstring

    One of: a, b.

  • variants[].sentinteger
  • variants[].clickedinteger
  • variants[].ctrnumber
  • languagesarray of objectrequired
  • languages[].languagestring

    Two letters, or unknown.

  • languages[].sentinteger
  • languages[].clickedinteger
  • errorsarray of objectrequired
  • errors[].codestring

    What the push service answered (an HTTP status, timeout, …), or expired.

  • errors[].countinteger
  • revenuenumberrequired
  • currencystring or nullrequired

    The website's revenue currency, or null.

  • sendBodyobject or nullrequired

    The POST /notifications body that makes this send again, or a draft's saved fields. null for automation, journey and product-alert sends.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

• 404Not found

  not_found

Example

curl "https://relaybell.com/api/v1/notifications/5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The draft's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

The same fields as Send a notification.

Responses

• 200The draft now.
  Response fields

  • oktruerequired
  • notificationIdstring (uuid)required
  • status"draft"required
  • sendBodyobjectrequired

    The draft's fields now.

• 400Bad request

  invalid_json

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 409Conflict

  not_a_draft

• 413Too large

  draft_too_largepayload_too_large

Example

curl -X PATCH https://relaybell.com/api/v1/notifications/ID \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn sale — last day"
  }'

Path parameters

• idstring (uuid)required

  The draft's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Responses

• 200Deleted.
  Response fields

  • oktruerequired
  • deletedtruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 409Conflict

  not_a_draft

Example

curl -X DELETE https://relaybell.com/api/v1/notifications/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The draft's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json · optional

The same fields as Send a notification.

Responses

• 202Accepted.

  The same answer as Send a notification.

• 400Bad request

  invalid_jsontitle_requiredunknown_fieldexternal_ids_emptyunknown_topicsegment_not_found

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  email_not_verifiedaccount_suspendedinsufficient_scope

• 404Not found

  not_found

• 409Conflict

  not_a_draft

• 413Too large

  payload_too_large

• 429Too many requests

  rate_limitedsend_limit_reached

Example

curl -X POST https://relaybell.com/api/v1/notifications/ID/send \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "sendAt": "2026-11-01T09:00:00Z"
  }'

Path parameters

• idstring (uuid)required

  The notification id.

Responses

• 200Canceled.
  Response fields

  • oktruerequired
  • canceledtruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_schedulednot_found

Example

curl -X POST https://relaybell.com/api/v1/notifications/5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42/cancel \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• eventstring

  The event name (or name). Cut to 120 characters; missing: 400 event_required.

• namestring

  Another spelling of event.

• externalIdstring

  Your user id.

• subscriberIdstring (uuid)

  relaybell's subscriber id.

• endpointstring

  Only disqualifies a product-alert broadcast; it does not identify the person on this route.

• propertiesobject

  Anything; value or revenue (a number) makes it a conversion.

Responses

• 202Stored.
  Response fields

  • oktruerequired
  • eventIdstringrequired

    The stored event's id.

  • subscriberIdstring (uuid) or nullrequired

    The subscriber it was linked to, or null.

  • isConversionbooleanrequired

    purchase, order.completed, checkout.completed (or your conversionEvents), or any event with a numeric value / revenue — except cart.updated and checkout.started.

  • attributionobject or nullrequired

    The notification credited with this conversion (last delivered in the attribution window), or null.

  • attribution.notificationIdstring (uuid)
  • attribution.valuenumber
  • automationsTriggeredintegerrequired
  • sequencesEnrolledintegerrequired
  • productAlertsinteger

    Product alerts created (back_in_stock / price_drop naming no person).

  • alertAudienceinteger

    People the product alerts reach.

  • alertAudienceTruncatedboolean

    The audience was cut at 100,000.

  • dedupedboolean

    A price_drop for this product already went out in the last 10 minutes.

• 400Bad request

  invalid_jsonevent_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

• 429Too many requests

  rate_limited

Example

curl -X POST https://relaybell.com/api/v1/events \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "event": "purchase",
    "externalId": "user_123",
    "properties": {
      "value": 79.99,
      "orderId": "A123"
    }
  }'

Responses

• 200The events.
  Response fields

  • eventsarray of objectrequired
  • events[].idstringrequired
  • events[].namestringrequired
  • events[].external_idstring or null
  • events[].subscriber_idstring (uuid) or null
  • events[].propertiesobjectrequired
  • events[].created_atstring (date-time)required
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 429Too many requests

  rate_limited

Example

curl "https://relaybell.com/api/v1/events" \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The segments.
  Response fields

  • segmentsarray of Segmentrequired
  • segments[].idstring (uuid)required
  • segments[].namestringrequired
  • segments[].filtersFiltersrequired

    The segment filter format, shared by segments, inline send filters / excludeFilters, schedules and the audience list.

  • segments[].created_atstring (date-time)required
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/segments" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• namestringrequired

  Required (400 name_required).

• filtersFiltersrequired

  The segment filter format, shared by segments, inline send filters / excludeFilters, schedules and the audience list.

• filters.matchstring

  all = every rule must match (default), any = at least one.

  One of: all, any. Default "all".

• filters.rulesarray of Rule

  The rules.

  Its fields: see Send a notification.

Responses

• 201Created.
  Response fields

  • segmentSegmentrequired

    Its fields: see List segments.

• 400Bad request

  invalid_jsonname_requiredsegment_needs_a_rule

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/segments \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Indian Pro users",
    "filters": {
      "match": "all",
      "rules": [
        {
          "field": "country",
          "op": "in",
          "value": [
            "IN"
          ]
        },
        {
          "field": "tag:plan",
          "op": "eq",
          "value": "pro"
        }
      ]
    }
  }'

Path parameters

• idstring (uuid)required

  The segment's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

• namestring
• filtersFilters

  The segment filter format, shared by segments, inline send filters / excludeFilters, schedules and the audience list.

• filters.matchstring

  all = every rule must match (default), any = at least one.

  One of: all, any. Default "all".

• filters.rulesarray of Rule

  The rules.

  Its fields: see Send a notification.

Responses

• 200The segment now.
  Response fields

  • segmentSegmentrequired

    Its fields: see List segments.

• 400Bad request

  invalid_jsonnothing_to_updatesegment_needs_a_rule

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 413Too large

  payload_too_large

Example

curl -X PUT https://relaybell.com/api/v1/segments/ID \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Indian Pro users (all devices)"
  }'

Path parameters

• idstring (uuid)required

  The segment id (not a UUID: 404 not_found).

Responses

• 200Done.
  Response fields

  • oktruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 409Conflict

  segment_in_use

Example

curl -X DELETE https://relaybell.com/api/v1/segments/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json · optional

• filtersFilters

  The segment filter format, shared by segments, inline send filters / excludeFilters, schedules and the audience list.

• filters.matchstring

  all = every rule must match (default), any = at least one.

  One of: all, any. Default "all".

• filters.rulesarray of Rule

  The rules.

  Its fields: see Send a notification.

• topicIdstring

  A topic id or slug.

Responses

• 200The count.
  Response fields

  • countintegerrequired
• 400Bad request

  invalid_json

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/segments/preview \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "match": "all",
      "rules": [
        {
          "field": "country",
          "op": "in",
          "value": [
            "IN"
          ]
        },
        {
          "field": "tag:plan",
          "op": "eq",
          "value": "pro"
        }
      ]
    }
  }'

Responses

• 200The segments.
  Response fields

  • segmentsarray of Segmentrequired

    Its fields: see List segments.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

Example

curl "https://relaybell.com/api/v1/audience/segments" \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The topics.
  Response fields

  • topicsarray of Topicrequired
  • topics[].idstring (uuid)required
  • topics[].namestringrequired
  • topics[].slugstringrequired

    Subscribers opt in by slug; it never changes.

  • topics[].created_atstring (date-time)required
  • topics[].subscribersintegerrequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/topics" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• namestringrequired

  Required (400 name_required).

• slugstring

  Letters, digits and dashes.

Responses

• 201Created (or renamed).
  Response fields

  • topicTopicrequired

    Its fields: see List topics.

• 400Bad request

  invalid_jsonname_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/topics \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Deals",
    "slug": "deals"
  }'

Path parameters

• idstring (uuid)required

  The topic's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

• namestringrequired

  Required (400 name_required).

Responses

• 200The topic now.
  Response fields

  • topicTopicrequired

    Its fields: see List topics.

• 400Bad request

  invalid_jsonname_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 413Too large

  payload_too_large

Example

curl -X PUT https://relaybell.com/api/v1/topics/ID \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Deals & offers"
  }'

Path parameters

• idstring (uuid)required

  The topic id (not a UUID: 404 not_found).

Responses

• 200Done.
  Response fields

  • oktruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl -X DELETE https://relaybell.com/api/v1/topics/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The CSV file (attachment; filename="relaybell-subscribers.csv").text/csv
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

Example

curl "https://relaybell.com/api/v1/subscribers/export" \
  -H "Authorization: Bearer rb_live_xxxxx"

Query parameters

• limitinteger

  Items per page, 1–100 (default 25).

  Default 25.

Responses

• 200The subscribers.
  Response fields

  • subscribersarray of SubscriberRowrequired
  • subscribers[].idstring (uuid)required
  • subscribers[].external_idstring or null
  • subscribers[].countrystring or null
  • subscribers[].languagestring or null
  • subscribers[].timezonestring or null
  • subscribers[].created_atstring (date-time)required
  • subscribers[].unsubscribed_atstring (date-time) or null
  • subscribers[].devicestring or null

    The most recently seen device type.

  • subscribers[].last_seen_atstring (date-time) or null
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

Example

curl "https://relaybell.com/api/v1/subscribers/recent" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• subscribersarray of objectrequired

  At least one (400 no_subscribers).

  Range: at most 10000.

• subscribers[].externalIdstringrequired

  Also accepted as external_id.

• subscribers[].tagsmap of string or number or boolean or null
• subscribers[].topicsarray of string

  Topic slugs.

Responses

• 200Processed.
  Response fields

  • oktruerequired
  • processedintegerrequired

    Rows with an external id.

  • notestring
• 400Bad request

  invalid_jsonno_subscribers

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/subscribers/import \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "subscribers": [
      {
        "externalId": "user_123",
        "tags": {
          "plan": "pro",
          "name": "Jane"
        },
        "topics": [
          "deals"
        ]
      }
    ]
  }'

Path parameters

• externalIdstringrequired

  Your external id for the person, or relaybell's subscriber id. Unknown: 404 not_found.

Responses

• 200The data.
  Response fields

  • subscriberobjectrequired

    The stored subscriber row.

  • tagsarray of objectrequired
  • tags[].keystring
  • tags[].valuestring or null
  • endpointsarray of objectrequired
  • endpoints[].idstring (uuid)
  • endpoints[].typestring
  • endpoints[].devicestring or null
  • endpoints[].user_agentstring or null
  • endpoints[].created_atstring (date-time)
  • endpoints[].last_seen_atstring (date-time) or null
  • deliveryEventsarray of objectrequired
  • deliveryEvents[].typestring
  • deliveryEvents[].notification_idstring (uuid) or null
  • deliveryEvents[].devicestring or null
  • deliveryEvents[].created_atstring (date-time)
  • behavioralEventsarray of objectrequired
  • behavioralEvents[].namestring
  • behavioralEvents[].propertiesobject
  • behavioralEvents[].created_atstring (date-time)
  • productInterestsarray of objectrequired
  • productInterests[].product_idstring
  • productInterests[].kindstring
  • productInterests[].created_atstring (date-time)
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl "https://relaybell.com/api/v1/subscribers/EXTERNAL_ID/data" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• externalIdstringrequired

  Your external id for the person, or relaybell's subscriber id. Unknown: 404 not_found.

Responses

• 200The profile.
  Response fields

  • subscriberobjectrequired
  • subscriber.idstring (uuid)required
  • subscriber.externalIdstring or null
  • subscriber.countrystring or null
  • subscriber.languagestring or null
  • subscriber.timezonestring or null
  • subscriber.createdAtstring (date-time)
  • subscriber.unsubscribedAtstring (date-time) or null
  • subscriber.consentAtstring (date-time) or null
  • tagsarray of objectrequired
  • tags[].keystring
  • tags[].valuestring or null
  • endpointsarray of objectrequired
  • endpoints[].idstring (uuid)
  • endpoints[].devicestring or null
  • endpoints[].user_agentstring or null
  • endpoints[].created_atstring (date-time)
  • endpoints[].last_seen_atstring (date-time) or null
  • topicsarray of objectrequired
  • topics[].namestring
  • topics[].slugstring
  • sendsarray of objectrequired
  • sends[].typestring
  • sends[].notification_idstring (uuid) or null
  • sends[].created_atstring (date-time)
  • sends[].titlestring or null
  • eventsarray of objectrequired
  • events[].namestring
  • events[].propertiesobject
  • events[].created_atstring (date-time)
  • statsobjectrequired
  • stats.deliveredintegerrequired
  • stats.clickedintegerrequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl "https://relaybell.com/api/v1/subscribers/user_123/profile" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• externalIdstringrequired

  Your external id for the person, or relaybell's subscriber id. Unknown: 404 not_found.

Responses

• 200Erased.
  Response fields

  • oktruerequired
  • erasedtruerequired
  • subscriberIdstring (uuid)required
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl -X DELETE https://relaybell.com/api/v1/subscribers/EXTERNAL_ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Query parameters

• limitinteger

  Items per page, 1–100 (default 25).

  Default 25.

• cursorstring

  The nextCursor from the previous page (send the same filters again). Anything else answers 400 invalid_cursor.

• qstring

  A subscriber id (exact) or part of an external id.

• statusstring

  Default all.

  One of: all, subscribed, unsubscribed, no_device. Default "all".

• countrystring

  2-letter codes, comma-separated.

• languagestring

  "en" matches en, en-US, en-GB…; "en-US" matches only en-US.

• devicestring

  desktop, android, ios, mobile, other (400 invalid_device).

• topicstring

  Topic ids or slugs (up to 5); an unknown one matches nobody.

• tagstring

  key (has the label) or key:value / key=value (with that value); up to 10.

• joinedFromstring (date)

  Joined on or after this day (YYYY-MM-DD, in tz).

• joinedTostring (date)

  Joined on or before this day.

• seenFromstring (date)

  Last seen on or after this day.

• seenTostring (date)

  Last seen on or before this day.

• tzstring

  IANA time zone for the days (default UTC).

• filtersstring

  Segment rules as JSON, e.g. {"match":"all","rules":[…]} (at most 20 rules; 400 invalid_filters).

• countstring

  "1" or "true" adds total, the number of matches.

  One of: 1, true.

Responses

• 200A page of subscribers.
  Response fields

  • itemsarray of AudienceSubscriberrequired
  • items[].idstring (uuid)required
  • items[].externalIdstring or null
  • items[].countrystring or null
  • items[].languagestring or null
  • items[].timezonestring or null
  • items[].statusstringrequired

    One of: subscribed, unsubscribed, no_device.

  • items[].devicestring or null
  • items[].devicesarray of string
  • items[].topicsarray of object
  • items[].tagsarray of object

    Up to 20; rb_ labels are left out.

  • items[].createdAtstring (date-time)required
  • items[].lastSeenAtstring (date-time) or null
  • items[].unsubscribedAtstring (date-time) or null
  • nextCursorstring or nullrequired
  • totalinteger

    Only with count=1.

• 400Bad request

  invalid_statusinvalid_deviceinvalid_rangeinvalid_tzinvalid_filtersinvalid_cursor

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

Example

curl "https://relaybell.com/api/v1/audience/subscribers" \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The options.
  Response fields

  • countriesarray of objectrequired
  • countries[].valuestring
  • countries[].countinteger
  • languagesarray of objectrequired
  • languages[].valuestring
  • languages[].countinteger
  • devicesarray of objectrequired
  • devices[].valuestring
  • devices[].countinteger
  • tagsarray of objectrequired
  • tags[].keystring
  • tags[].countinteger
  • tags[].valuesarray of string
  • topicsarray of objectrequired
  • topics[].idstring (uuid)
  • topics[].namestring
  • topics[].slugstring
  • topics[].countinteger
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

Example

curl "https://relaybell.com/api/v1/audience/subscribers/facets" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• idsarray of string (uuid)required

  Subscriber ids (400 ids_required, too_many_ids, invalid_id).

  Range: at most 1000.

• setmap of string or null

  Labels to add or change: { key: value }.

• removearray of string

  Label names to remove.

Responses

• 200Done.
  Response fields

  • oktruerequired
  • updatedintegerrequired
• 400Bad request

  invalid_jsonnothing_to_changetoo_many_labelsinvalid_labelreserved_labelids_requiredtoo_many_idsinvalid_id

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/audience/subscribers/bulk-tag \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "e1c9b7a5-3d2f-4e8b-9a6c-0f4d2b8e1a73"
    ],
    "set": {
      "plan": "pro"
    },
    "remove": [
      "trial"
    ]
  }'

Request body · application/json

• idsarray of string (uuid)required

  Range: at most 1000.

Responses

• 200Done.
  Response fields

  • oktruerequired
  • deletedintegerrequired
• 400Bad request

  invalid_jsonids_requiredtoo_many_idsinvalid_id

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/audience/subscribers/bulk-delete \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "e1c9b7a5-3d2f-4e8b-9a6c-0f4d2b8e1a73"
    ]
  }'

Responses

• 200The webhooks.
  Response fields

  • webhooksarray of Webhookrequired
  • webhooks[].idstring (uuid)required
  • webhooks[].urlstringrequired
  • webhooks[].eventsarray of stringrequired

    Empty = every event.

  • webhooks[].enabledbooleanrequired
  • webhooks[].last_statusinteger or null

    HTTP status of the last attempt (0 when no answer came back).

  • webhooks[].last_fired_atstring (date-time) or null
  • webhooks[].created_atstring (date-time)required
  • webhooks[].consecutive_failuresintegerrequired

    Deliveries failed in a row since the last success.

  • webhooks[].failing_sincestring (date-time) or null

    First failure since the last success.

  • webhooks[].disabled_reasonstring or null

    Set when relaybell turned it off.

    One of: failed_50_in_a_row, failing_for_3_days.

  • webhooks[].disabled_atstring (date-time) or null
  • eventsarray of stringrequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/webhooks" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• urlstringrequired

  Where to POST events.

• eventsarray of string

  Empty or left out = every event.

Responses

• 201Created. The only time you see the secret.
  Response fields

  • webhookobjectrequired
  • webhook.idstring (uuid)required
  • webhook.urlstringrequired
  • webhook.eventsarray of stringrequired
  • webhook.secretstringrequired
  • webhook.enabledbooleanrequired
  • webhook.created_atstring (date-time)required
• 400Bad request

  invalid_jsoninvalid_url

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/webhooks \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example/webhooks/relaybell",
    "events": [
      "notification.clicked"
    ]
  }'

Path parameters

• idstring (uuid)required

  The webhook's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

• urlstring

  Must start with http:// or https://.

• eventsarray of string
• enabledboolean

Responses

• 200The webhook now.
  Response fields

  • webhookWebhookrequired

    Its fields: see List webhooks.

• 400Bad request

  invalid_jsoninvalid_urlnothing_to_update

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 413Too large

  payload_too_large

Example

curl -X PUT https://relaybell.com/api/v1/webhooks/c3e5a7b9-2d4f-4a6c-8e0b-1d3f5a7c9e2b \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

Path parameters

• idstring (uuid)required

  The webhook id.

Responses

• 200Done.
  Response fields

  • oktruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

Example

curl -X DELETE https://relaybell.com/api/v1/webhooks/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The webhook's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Query parameters

• limitinteger

  Items per page, 1–100 (default 25).

  Default 25.

• cursorstring

  The nextCursor from the previous page (send the same filters again). Anything else answers 400 invalid_cursor.

Responses

• 200A page of deliveries.
  Response fields

  • deliveriesarray of WebhookDeliveryrequired
  • deliveries[].idstring (uuid)required

    The delivery id, also sent as X-Relaybell-Delivery (the same on every retry and resend).

  • deliveries[].eventstringrequired
  • deliveries[].statusstringrequired

    pending (waiting for its first attempt, or a resend / test waiting to run), retrying, succeeded (the last attempt got a 2xx) or failed.

    One of: pending, retrying, succeeded, failed.

  • deliveries[].attemptsintegerrequired

    Every attempt, resends included.

  • deliveries[].last_status_codeinteger or null

    null when no answer came back (error says why).

  • deliveries[].duration_msinteger or null
  • deliveries[].errorstring or null

    Why the last attempt failed, in plain words.

  • deliveries[].created_atstring (date-time)required
  • deliveries[].last_attempt_atstring (date-time) or null
  • deliveries[].next_attempt_atstring (date-time) or null

    When the next retry runs.

  • deliveries[].delivered_atstring (date-time) or null
  • nextCursorstring or nullrequired
• 400Bad request

  invalid_cursor

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl "https://relaybell.com/api/v1/webhooks/c3e5a7b9-2d4f-4a6c-8e0b-1d3f5a7c9e2b/deliveries?limit=25" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The webhook's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

• deliveryIdstring (uuid)required

  The delivery id (X-Relaybell-Delivery).

Responses

• 200The delivery.
  Response fields

  • deliveryWebhookDeliveryDetailrequired
  • delivery.idstring (uuid)required

    The delivery id, also sent as X-Relaybell-Delivery (the same on every retry and resend).

  • delivery.eventstringrequired
  • delivery.statusstringrequired

    pending (waiting for its first attempt, or a resend / test waiting to run), retrying, succeeded (the last attempt got a 2xx) or failed.

    One of: pending, retrying, succeeded, failed.

  • delivery.attemptsintegerrequired

    Every attempt, resends included.

  • delivery.last_status_codeinteger or null

    null when no answer came back (error says why).

  • delivery.duration_msinteger or null
  • delivery.errorstring or null

    Why the last attempt failed, in plain words.

  • delivery.created_atstring (date-time)required
  • delivery.last_attempt_atstring (date-time) or null
  • delivery.next_attempt_atstring (date-time) or null

    When the next retry runs.

  • delivery.delivered_atstring (date-time) or null
  • delivery.webhook_idstring (uuid)
  • delivery.request_bodystring

    Exactly what was signed and sent, up to 64 KB.

  • delivery.request_truncatedboolean

    true when the body was longer than 64 KB.

  • delivery.request_headersobject or null

    The last attempt's headers (content-type, user-agent, x-relaybell-event, x-relaybell-delivery and both signatures). Never your secret.

  • delivery.response_bodystring or null

    The first 2 KB of your server's last answer.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl "https://relaybell.com/api/v1/webhooks/c3e5a7b9-2d4f-4a6c-8e0b-1d3f5a7c9e2b/deliveries/f0e1d2c3-b4a5-4697-8869-5a4b3c2d1e0f" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The webhook's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

• deliveryIdstring (uuid)required

  The delivery id.

Responses

• 202Queued.
  Response fields

  • deliveryWebhookDeliveryrequired

    Its fields: see Get one delivery.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 409Conflict

  delivery_in_progressbody_too_large

• 429Too many requests

  rate_limited

Example

curl -X POST https://relaybell.com/api/v1/webhooks/c3e5a7b9-2d4f-4a6c-8e0b-1d3f5a7c9e2b/deliveries/f0e1d2c3-b4a5-4697-8869-5a4b3c2d1e0f/resend \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The webhook's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Responses

• 202Queued.
  Response fields

  • deliveryWebhookDeliveryrequired

    Its fields: see Get one delivery.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 429Too many requests

  rate_limited

Example

curl -X POST https://relaybell.com/api/v1/webhooks/c3e5a7b9-2d4f-4a6c-8e0b-1d3f5a7c9e2b/test \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The automations.
  Response fields

  • automationsarray of AutomationWithStatsrequired
  • automations[].idstring (uuid)required
  • automations[].project_idstring (uuid)
  • automations[].namestringrequired
  • automations[].enabledbooleanrequired
  • automations[].eventstringrequired

    The event name that starts it.

  • automations[].conditionsarray of objectrequired
  • automations[].actionobjectrequired
  • automations[].delay_secondsintegerrequired
  • automations[].cancel_onstring or null
  • automations[].once_per_subscriberboolean
  • automations[].created_atstring (date-time)required
  • automations[].sentintegerrequired

    All-time deliveries.

  • automations[].stats30dStats30drequired

    The last 30 days, from the notifications it produced.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/automations" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• eventstringrequired

  The event name that starts it (required: 400 event_required). Up to 120 characters.

• actionobject

  The push. Merge tags take values from the event's properties: {product}, {url}, {price|} …

• action.titlestring

  Required (400 action_title_required on create).

• action.bodystring
• action.urlstring
• action.iconstring
• namestring

  Up to 120 characters (default "Automation").

• delaySecondsinteger

  Wait before sending (default 0). A newer event from the same person replaces their pending one.

• cancelOnstring

  An event name that cancels the person's pending push, e.g. purchase.

• conditionsarray of object

  Checked against the event's properties; all must match. On PUT, left out = kept as they are.

• conditions[].fieldstringrequired
• conditions[].opstring

  One of: eq, neq, contains, exists, gt, gte, lt, lte. Default "eq".

• conditions[].valueany
• oncePerSubscriberboolean

  At most once per person, ever.

• enabledboolean

  Default true. On PUT, it goes back to true unless you send false.

Responses

• 201Created.
  Response fields

  • automationAutomationrequired

    Its fields: see List automations.

• 400Bad request

  invalid_jsonevent_requiredaction_title_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/automations \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Cart abandon",
    "event": "cart.updated",
    "delaySeconds": 3600,
    "cancelOn": "purchase",
    "conditions": [
      {
        "field": "cartTotal",
        "op": "gte",
        "value": 20
      }
    ],
    "action": {
      "title": "You left {product|something} in your cart 🛒",
      "body": "Complete your order before it's gone.",
      "url": "{url}"
    }
  }'

Path parameters

• idstring (uuid)required

  The automation's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Responses

• 200The automation.
  Response fields

  • automationAutomationWithStatsrequired

    Its fields: see List automations.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

• 404Not found

  not_found

Example

curl "https://relaybell.com/api/v1/automations/ID" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The automation's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

The same fields as Create an automation.

Responses

• 200The automation now.
  Response fields

  • automationAutomationrequired

    Its fields: see List automations.

• 400Bad request

  invalid_jsonevent_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 413Too large

  payload_too_large

Example

curl -X PUT https://relaybell.com/api/v1/automations/ID \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Cart abandon",
    "event": "cart.updated",
    "delaySeconds": 7200,
    "cancelOn": "purchase",
    "action": {
      "title": "Still thinking it over?",
      "url": "{url}"
    }
  }'

Path parameters

• idstring (uuid)required

  The automation id (not a UUID: 404 not_found).

Responses

• 200Done.
  Response fields

  • oktruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl -X DELETE https://relaybell.com/api/v1/automations/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The journeys.
  Response fields

  • sequencesarray of JourneyWithStatsrequired
  • sequences[].idstring (uuid)required
  • sequences[].project_idstring (uuid)
  • sequences[].namestringrequired
  • sequences[].enabledbooleanrequired
  • sequences[].trigger_typestringrequired

    One of: subscribe, event.

  • sequences[].trigger_eventstring or null
  • sequences[].cancel_onstring or null
  • sequences[].created_atstring (date-time)required
  • sequences[].stepsarray of JourneySteprequired
  • sequences[].enrollmentsobjectrequired
  • sequences[].stats30dStats30drequired

    The last 30 days, from the notifications it produced.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/sequences" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• namestring

  Up to 120 characters (default "Sequence").

• triggerstring

  "subscribe" (default) or "event".

  One of: subscribe, event.

• triggerEventstring

  Required with "event" (400 trigger_event_required).

• cancelOnstring

  An event that takes the person out of the journey, e.g. purchase.

• enabledboolean

  Default true.

• stepsarray of object

  At least one (400 at_least_one_step_required). On PUT, steps change only when you send them.

• steps[].idstring (uuid)

  An existing step's id, to keep it (and its numbers) when editing.

• steps[].typestring

  "message" (default) or "branch".

  One of: message, branch.

• steps[].delaySecondsinteger

  The wait after the previous step (for the first step, after entering).

• steps[].titlestring

  A message step without a title is dropped.

• steps[].bodystring
• steps[].urlstring
• steps[].iconstring
• steps[].conditionobject

  Branch: the person goes on only if they match (segment rule format).

• condition.fieldstringrequired
• condition.opstring
• condition.valuestring

Responses

• 201Created (the steps are in GET /sequences/{id}).
  Response fields

  • sequenceJourneyrequired

    Its fields: see List journeys.

• 400Bad request

  invalid_jsontrigger_event_requiredat_least_one_step_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/sequences \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome series",
    "trigger": "subscribe",
    "cancelOn": "purchase",
    "steps": [
      {
        "delaySeconds": 0,
        "title": "Welcome 👋",
        "url": "https://shop.example"
      },
      {
        "delaySeconds": 86400,
        "title": "Here's how to start"
      },
      {
        "type": "branch",
        "condition": {
          "field": "tag:plan",
          "op": "eq",
          "value": "free"
        }
      },
      {
        "delaySeconds": 604800,
        "title": "A little something for you"
      }
    ]
  }'

Path parameters

• idstring (uuid)required

  The journey's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Responses

• 200The journey.
  Response fields

  • sequenceJourneyWithStatsrequired

    Its fields: see List journeys.

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

• 404Not found

  not_found

Example

curl "https://relaybell.com/api/v1/sequences/ID" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The journey's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

The same fields as Create a journey.

Responses

• 200The journey now (without steps).
  Response fields

  • sequenceJourneyrequired

    Its fields: see List journeys.

• 400Bad request

  invalid_jsontrigger_event_requiredat_least_one_step_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 409Conflict

  structural_change_requires_no_active_enrollments

• 413Too large

  payload_too_large

Example

curl -X PUT https://relaybell.com/api/v1/sequences/ID \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome series",
    "trigger": "subscribe",
    "cancelOn": "purchase",
    "enabled": false
  }'

Path parameters

• idstring (uuid)required

  The journey id (not a UUID: 404 not_found).

Responses

• 200Done.
  Response fields

  • oktruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl -X DELETE https://relaybell.com/api/v1/sequences/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The feeds.
  Response fields

  • feedsarray of Feedrequired
  • feeds[].idstring (uuid)required
  • feeds[].urlstringrequired
  • feeds[].enabledbooleanrequired
  • feeds[].segment_idstring (uuid) or nullrequired
  • feeds[].last_guidstring or null
  • feeds[].last_checked_atstring (date-time) or null
  • feeds[].created_atstring (date-time)
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/feeds" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• urlstringrequired

  http(s) feed URL (400 invalid_url).

• segmentIdstring (uuid)

  A segment of this website (400 invalid_segment).

Responses

• 201Added.
  Response fields

  • feedFeedrequired

    Its fields: see List RSS feeds.

• 400Bad request

  invalid_jsoninvalid_urlinvalid_segment

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/feeds \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "url": "https://blog.example/feed.xml"
  }'

Path parameters

• idstring (uuid)required

  The feed's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

• enabledboolean
• segmentIdstring (uuid) or null

Responses

• 200The feed now.
  Response fields

  • feedobjectrequired
  • feed.idstring (uuid)required
  • feed.urlstringrequired
  • feed.enabledbooleanrequired
  • feed.segment_idstring (uuid) or nullrequired
• 400Bad request

  invalid_jsonnothing_to_updateinvalid_segment

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 413Too large

  payload_too_large

Example

curl -X PUT https://relaybell.com/api/v1/feeds/ID \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Path parameters

• idstring (uuid)required

  The feed id (not a UUID: 404 not_found).

Responses

• 200Done.
  Response fields

  • oktruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl -X DELETE https://relaybell.com/api/v1/feeds/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The schedules.
  Response fields

  • schedulesarray of Schedulerequired
  • schedules[].idstring (uuid)required
  • schedules[].project_idstring (uuid)
  • schedules[].namestringrequired
  • schedules[].contentobjectrequired

    { title, body, url, icon, segmentId | filters, topicId, excludeSegmentId | excludeFilters }

  • schedules[].cadencestringrequired

    One of: hourly, daily, weekly.

  • schedules[].at_timestring or null

    "HH:MM".

  • schedules[].day_of_weekinteger or null

    0–6, 0 = Sunday.

  • schedules[].timezonestringrequired
  • schedules[].enabledbooleanrequired
  • schedules[].next_run_atstring (date-time) or null
  • schedules[].last_run_atstring (date-time) or null
  • schedules[].created_atstring (date-time)
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/schedules" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• namestring

  Up to 120 characters (default "Recurring campaign").

• contentobjectrequired
• content.titlestringrequired

  Required (400 content_title_required).

• content.bodystring
• content.urlstring
• content.iconstring
• content.segmentIdstring (uuid)
• content.filtersFilters

  The segment filter format, shared by segments, inline send filters / excludeFilters, schedules and the audience list.

• filters.matchstring

  all = every rule must match (default), any = at least one.

  One of: all, any. Default "all".

• filters.rulesarray of Rule

  The rules.

• content.topicIdstring

  Id or slug (400 unknown_topic).

• content.excludeSegmentIdstring (uuid)
• content.excludeFiltersFilters

  The segment filter format, shared by segments, inline send filters / excludeFilters, schedules and the audience list.

• excludeFilters.matchstring

  all = every rule must match (default), any = at least one.

  One of: all, any. Default "all".

• excludeFilters.rulesarray of Rule

  The rules.

• cadencestring

  Default daily.

  One of: hourly, daily, weekly. Default "daily".

• atTimestring

  "HH:MM" (default "09:00").

  Default "09:00".

• dayOfWeekinteger

  0–6, 0 = Sunday (default 1).

  Default 1. Range: 0–6.

• timezonestring

  An IANA name (default UTC; 400 invalid_timezone).

  Default "UTC".

• enabledboolean

  Default true.

Responses

• 201Created.
  Response fields

  • scheduleSchedulerequired

    Its fields: see List recurring campaigns.

• 400Bad request

  invalid_jsoncontent_title_requiredinvalid_timezoneunknown_topic

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/schedules \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Daily digest",
    "content": {
      "title": "Today's picks",
      "url": "https://shop.example/today",
      "topicId": "deals"
    },
    "cadence": "daily",
    "atTime": "09:00",
    "timezone": "Asia/Kolkata"
  }'

Path parameters

• idstring (uuid)required

  The schedule's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

The same fields as Create a recurring campaign.

Responses

• 200The schedule now.
  Response fields

  • scheduleSchedulerequired

    Its fields: see List recurring campaigns.

• 400Bad request

  invalid_jsoncontent_title_requiredinvalid_timezoneunknown_topic

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 413Too large

  payload_too_large

Example

curl -X PUT https://relaybell.com/api/v1/schedules/ID \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Daily digest",
    "content": {
      "title": "Today's picks"
    },
    "cadence": "weekly",
    "dayOfWeek": 1,
    "atTime": "10:00",
    "timezone": "UTC",
    "enabled": true
  }'

Path parameters

• idstring (uuid)required

  The schedule id (not a UUID: 404 not_found).

Responses

• 200Done.
  Response fields

  • oktruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl -X DELETE https://relaybell.com/api/v1/schedules/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The templates.
  Response fields

  • templatesarray of Templaterequired
  • templates[].idstring (uuid)required
  • templates[].namestringrequired
  • templates[].contentobjectrequired

    Any object, e.g. a send body.

  • templates[].created_atstring (date-time)required
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/templates" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• namestringrequired

  Required (400 name_required).

• contentobject

Responses

• 201Created.
  Response fields

  • templateTemplaterequired

    Its fields: see List templates.

• 400Bad request

  invalid_jsonname_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/templates \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Sale",
    "content": {
      "title": "Flash sale 🔥",
      "body": "30% off ends tonight"
    }
  }'

Path parameters

• idstring (uuid)required

  The template's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

• namestringrequired

  Required (400 name_required).

• contentobject

Responses

• 200The template now.
  Response fields

  • templateTemplaterequired

    Its fields: see List templates.

• 400Bad request

  invalid_jsonname_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 413Too large

  payload_too_large

Example

curl -X PUT https://relaybell.com/api/v1/templates/ID \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Sale",
    "content": {
      "title": "Last day of the sale"
    }
  }'

Path parameters

• idstring (uuid)required

  The template id (not a UUID: 404 not_found).

Responses

• 200Done.
  Response fields

  • oktruerequired
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

Example

curl -X DELETE https://relaybell.com/api/v1/templates/ID \
  -H "Authorization: Bearer rb_live_xxxxx"

Responses

• 200The goals.
  Response fields

  • goalsarray of Goalrequired
  • goals[].idstring (uuid)required
  • goals[].namestringrequired
  • goals[].eventNamestringrequired
  • goals[].createdAtstring (date-time)required
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/goals" \
  -H "Authorization: Bearer rb_live_xxxxx"

Request body · application/json

• namestringrequired

  Up to 80 characters.

• eventNamestringrequired

  Up to 120 characters.

Responses

• 201Created (or changed).
  Response fields

  • goalGoalrequired

    Its fields: see List conversion goals.

• 400Bad request

  invalid_jsonname_and_event_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 413Too large

  payload_too_large

Example

curl -X POST https://relaybell.com/api/v1/goals \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "name": "Purchases",
    "eventName": "purchase"
  }'

Query parameters

• daysinteger

  1–365 (default 30).

  Default 30.

Responses

• 200The report.
  Response fields

  • windowDaysintegerrequired
  • funnelobjectrequired
  • funnel.deliveredintegerrequired
  • funnel.clickedintegerrequired
  • goalsarray of objectrequired
  • goals[].idstring (uuid)
  • goals[].namestring
  • goals[].eventNamestring
  • goals[].conversionsinteger
  • goals[].subscribersinteger
  • goals[].revenuenumber
• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspended

Example

curl "https://relaybell.com/api/v1/goals/stats" \
  -H "Authorization: Bearer rb_live_xxxxx"

Path parameters

• idstring (uuid)required

  The goal's id. One that isn't this website's — or isn't a UUID — answers 404 not_found.

Request body · application/json

• namestringrequired
• eventNamestringrequired

Responses

• 200The goal now.
  Response fields

  • goalGoalrequired

    Its fields: see List conversion goals.

• 400Bad request

  invalid_jsonname_and_event_required

• 401No valid credentials

  not_authenticatedinvalid_api_keyapi_key_expired

• 403Not allowed

  account_suspendedinsufficient_scope

• 404Not found

  not_found

• 409Conflict

  name_taken

• 413Too large

  payload_too_large