Notifications API

Who is told about what — by email, SMS, WhatsApp or in the app.

Module code notifications · 20 actions · 7 data models · 18 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: notifications (everything), notifications:read (read only) or notifications:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

notifications.create_channel

Add a delivery channel — Where notifications go: a webhook, a set of addresses, a Slack channel or a push endpoint.

Needs notifications:manage · changes data

• Canonical address: POST /api/v1/actions/notifications.create_channel

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.channel_created

What it writes: notification_channel (insert) — Adds the channel, unverified until something has reached it

curl -X POST https://app.getera.io/api/v1/notification_channels/actions/create_channel \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"webhook","name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.channel_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationChannels.createChannel({
  type: "webhook",
  name: "Name"
})

era notification_channels create_channel \
  --type "webhook" \
  --name "Name"

{
  "name": "era__notifications__create_channel",
  "arguments": {
    "type": "webhook",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_url, insecure_url, url_required, recipients_required, too_many_recipients, invalid_config, name_taken · 429 slow down

notifications.create_rule

Add a notification rule — Which events reach a channel or a person, in which words, and how often.

Needs notifications:manage · changes data

• Canonical address: POST /api/v1/actions/notifications.create_rule

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.rule_created

What it writes: notification_rule (insert) — Adds the rule, active

curl -X POST https://app.getera.io/api/v1/notification_rules/actions/create_rule \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.rule_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationRules.createRule({
  name: "Name"
})

era notification_rules create_rule \
  --name "Name"

{
  "name": "era__notifications__create_rule",
  "arguments": {
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 channel_not_found, trace_needs_webhook, invalid_condition, cooldown_out_of_range, name_taken, rule_limit_reached, recipient_incomplete · 429 slow down

notifications.delete_channel

Remove a delivery channel — Refused while a rule still points at it, so no rule is silently orphaned.

Needs notifications:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/notifications.delete_channel

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.channel_deleted

What it writes: notification_channel (delete) — Removes the channel

curl -X POST https://app.getera.io/api/v1/notification_channels/actions/delete_channel \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channel_id":"CHANNEL_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.channel_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationChannels.deleteChannel({
  channel_id: "CHANNEL_ID"
})

era notification_channels delete_channel \
  --channel-id "CHANNEL_ID"

{
  "name": "era__notifications__delete_channel",
  "arguments": {
    "channel_id": "CHANNEL_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 channel_not_found, channel_in_use · 429 slow down

notifications.delete_rule

Remove a notification rule — Removes the rule and its delivery history. The channel stays.

Needs notifications:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/notifications.delete_rule

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.rule_deleted

What it writes: notification_rule (delete) — Removes the rule; its deliveries cascade

curl -X POST https://app.getera.io/api/v1/notification_rules/actions/delete_rule \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"rule_id":"RULE_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.rule_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationRules.deleteRule({
  rule_id: "RULE_ID"
})

era notification_rules delete_rule \
  --rule-id "RULE_ID"

{
  "name": "era__notifications__delete_rule",
  "arguments": {
    "rule_id": "RULE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 rule_not_found · 429 slow down

notifications.mark_read

Mark notifications read — Marks some or all of your in-app notifications read (or one unread again).

Needs notifications:read · changes data

• Canonical address: POST /api/v1/actions/notifications.mark_read

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.inbox_read

What it writes: notification_inbox (update) — Stamps read_at on your notifications

curl -X POST https://app.getera.io/api/v1/notification_inboxes/actions/mark_read \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ids":"Notifications"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.inbox_read"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationInboxes.markRead({
  ids: "Notifications"
})

era notification_inboxes mark_read \
  --ids "Notifications"

{
  "name": "era__notifications__mark_read",
  "arguments": {
    "ids": "Notifications"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 notification_not_found · 429 slow down

notifications.purge_history

Sweep delivery history — Removes finished deliveries older than the retention window. Pending ones are never touched.

Needs notifications:delete · removes or cannot be undone

• Canonical address: POST /api/v1/actions/notifications.purge_history

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.history_purged

What it writes: notification_delivery (delete) — Removes delivered, failed and suppressed rows older than the window

curl -X POST https://app.getera.io/api/v1/notification_deliveries/actions/purge_history \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"days":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.history_purged"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationDeliveries.purgeHistory({
  days: 1
})

era notification_deliveries purge_history \
  --days 1

{
  "name": "era__notifications__purge_history",
  "arguments": {
    "days": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 retention_too_short · 429 slow down

notifications.queue_delivery

Queue a notification — Writes the delivery, or writes why it was deliberately not sent.

Needs notifications:handle · changes data

• Canonical address: POST /api/v1/actions/notifications.queue_delivery

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.queued, notifications.suppressed

What it writes: notification_delivery (insert) — Writes the delivery as pending, or as suppressed with a reason; notification_rule (update) — Stamps the rule’s quiet period when it fires; notification_inbox (insert) — Puts an in-app notification in each person’s bell

curl -X POST https://app.getera.io/api/v1/notification_deliveries/actions/queue_delivery \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"rule_id":"RULE_ID","event_name":"Event"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.queued",
    "notifications.suppressed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationDeliveries.queueDelivery({
  rule_id: "RULE_ID",
  event_name: "Event"
})

era notification_deliveries queue_delivery \
  --rule-id "RULE_ID" \
  --event-name "Event"

{
  "name": "era__notifications__queue_delivery",
  "arguments": {
    "rule_id": "RULE_ID",
    "event_name": "Event"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 rule_not_found, event_not_matched · 429 slow down

notifications.record_site_email

Record a site email — Machine-only: an email the website already sent to a customer, written into the delivery log.

Needs notifications:handle · changes data

• Canonical address: POST /api/v1/actions/notifications.record_site_email

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: notification_delivery (insert) — Writes the delivered (or failed) email row

Errors: 401 no or expired credential · 403 the credential does not hold notifications:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_recipient · 429 slow down

notifications.reset_email_template

Restore the default wording — Drops this workspace’s wording of one customer email; the default applies again.

Needs notifications:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/notifications.reset_email_template

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.email_template_changed

What it writes: notification_email_template (delete) — Removes the workspace’s wording

curl -X POST https://app.getera.io/api/v1/notification_email_templates/actions/reset_email_template \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"Email"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.email_template_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationEmailTemplates.resetEmailTemplate({
  kind: "Email"
})

era notification_email_templates reset_email_template \
  --kind "Email"

{
  "name": "era__notifications__reset_email_template",
  "arguments": {
    "kind": "Email"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_email_template · 429 slow down

notifications.retry_delivery

Retry a notification — Puts a failed delivery back on the queue, due now, with its attempts reset.

Needs notifications:manage · changes data

• Canonical address: POST /api/v1/actions/notifications.retry_delivery

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.delivery_retried

What it writes: notification_delivery (update) — Returns the delivery to pending, due now

curl -X POST https://app.getera.io/api/v1/notification_deliveries/actions/retry_delivery \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"delivery_id":"DELIVERY_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.delivery_retried"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationDeliveries.retryDelivery({
  delivery_id: "DELIVERY_ID"
})

era notification_deliveries retry_delivery \
  --delivery-id "DELIVERY_ID"

{
  "name": "era__notifications__retry_delivery",
  "arguments": {
    "delivery_id": "DELIVERY_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 delivery_not_found, delivery_not_failed · 429 slow down

notifications.save_email_template

Save a customer email — Replaces the wording of one customer email for this workspace.

Needs notifications:manage · changes data

• Canonical address: POST /api/v1/actions/notifications.save_email_template

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.email_template_changed

What it writes: notification_email_template (upsert) — Writes the workspace’s wording

curl -X POST https://app.getera.io/api/v1/notification_email_templates/actions/save_email_template \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"Email","subject":"Subject","body":"Body"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.email_template_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationEmailTemplates.saveEmailTemplate({
  kind: "Email",
  subject: "Subject",
  body: "Body"
})

era notification_email_templates save_email_template \
  --kind "Email" \
  --subject "Subject" \
  --body "Body"

{
  "name": "era__notifications__save_email_template",
  "arguments": {
    "kind": "Email",
    "subject": "Subject",
    "body": "Body"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_email_template · 429 slow down

notifications.send_customer_message

Send a message to the customer — Queues one message to one customer — WhatsApp or SMS through a connected inbox, email through the branded sender, or the best of the three.

Needs notifications:handle · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/notifications.send_customer_message

Input

Events it publishes: notifications.queued

What it writes: notification_delivery (insert) — Writes a pending delivery to one customer on one medium

curl -X POST https://app.getera.io/api/v1/notification_deliveries/actions/send_customer_message \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customer_id":"CUSTOMER_ID","medium":"sms","text":"Message","event_name":"Event"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.queued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationDeliveries.sendCustomerMessage({
  customer_id: "CUSTOMER_ID",
  medium: "sms",
  text: "Message",
  event_name: "Event"
})

era notification_deliveries send_customer_message \
  --customer-id "CUSTOMER_ID" \
  --medium "sms" \
  --text "Message" \
  --event-name "Event"

{
  "name": "era__notifications__send_customer_message",
  "arguments": {
    "customer_id": "CUSTOMER_ID",
    "medium": "sms",
    "text": "Message",
    "event_name": "Event"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 429 slow down

notifications.send_email

Send an email — Queues one message to one address through an email channel and the real sender.

Needs notifications:handle · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/notifications.send_email

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.queued

What it writes: notification_delivery (insert) — Writes a pending delivery addressed to one recipient

curl -X POST https://app.getera.io/api/v1/notification_deliveries/actions/send_email \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"To","subject":"Subject","text":"Message","event_name":"Event"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.queued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationDeliveries.sendEmail({
  to: "To",
  subject: "Subject",
  text: "Message",
  event_name: "Event"
})

era notification_deliveries send_email \
  --to "To" \
  --subject "Subject" \
  --text "Message" \
  --event-name "Event"

{
  "name": "era__notifications__send_email",
  "arguments": {
    "to": "To",
    "subject": "Subject",
    "text": "Message",
    "event_name": "Event"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_recipient, no_email_channel, bad_connection · 429 slow down

notifications.send_test

Send a test notification — Queues one message to the channel through the real sender and records the outcome.

Needs notifications:manage · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/notifications.send_test

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.test_queued

What it writes: notification_delivery (insert) — Writes a pending test delivery

curl -X POST https://app.getera.io/api/v1/notification_deliveries/actions/send_test \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channel_id":"NOTIFICATION_CHANNEL_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.test_queued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationDeliveries.sendTest({
  channel_id: "NOTIFICATION_CHANNEL_ID"
})

era notification_deliveries send_test \
  --channel-id "NOTIFICATION_CHANNEL_ID"

{
  "name": "era__notifications__send_test",
  "arguments": {
    "channel_id": "NOTIFICATION_CHANNEL_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 channel_not_found · 429 slow down

notifications.send_test_email_template

Send a test email — Sends one customer email, filled with sample values, to an address you choose.

Needs notifications:manage · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/notifications.send_test_email_template

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.test_queued

What it writes: notification_delivery (insert) — Writes a pending test delivery to one address

curl -X POST https://app.getera.io/api/v1/notification_deliveries/actions/send_test_email_template \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"Email","to":"Send to"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.test_queued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationDeliveries.sendTestEmailTemplate({
  kind: "Email",
  to: "Send to"
})

era notification_deliveries send_test_email_template \
  --kind "Email" \
  --to "Send to"

{
  "name": "era__notifications__send_test_email_template",
  "arguments": {
    "kind": "Email",
    "to": "Send to"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_email_template, invalid_recipient, no_email_channel · 429 slow down

notifications.set_preference

Set a notification preference — Whether someone is told, on which channel type, and until when they are muted.

Needs notifications:read · changes data

• Canonical address: POST /api/v1/actions/notifications.set_preference

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.preference_changed

What it writes: notification_preference (upsert) — Writes the person’s preference for that channel type and event

curl -X POST https://app.getera.io/api/v1/notification_preferences/actions/set_preference \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channel_type":"webhook","enabled":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.preference_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationPreferences.setPreference({
  channel_type: "webhook",
  enabled: true
})

era notification_preferences set_preference \
  --channel-type "webhook" \
  --enabled true

{
  "name": "era__notifications__set_preference",
  "arguments": {
    "channel_type": "webhook",
    "enabled": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_your_preference, not_a_member, mute_in_past · 429 slow down

notifications.set_rule_active

Switch a rule on or off — A rule that is off matches nothing and queues nothing.

Needs notifications:manage · changes data

• Canonical address: POST /api/v1/actions/notifications.set_rule_active

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.rule_enabled, notifications.rule_disabled

What it writes: notification_rule (update) — Flips the active flag and clears the quiet period

curl -X POST https://app.getera.io/api/v1/notification_rules/actions/set_rule_active \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"rule_id":"RULE_ID","active":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.rule_enabled",
    "notifications.rule_disabled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationRules.setRuleActive({
  rule_id: "RULE_ID",
  active: true
})

era notification_rules set_rule_active \
  --rule-id "RULE_ID" \
  --active true

{
  "name": "era__notifications__set_rule_active",
  "arguments": {
    "rule_id": "RULE_ID",
    "active": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 rule_not_found, no_change · 429 slow down

notifications.set_user_settings

Set my notification schedule — Timezone, language, quiet hours and email digest for one person.

Needs notifications:read · changes data

• Canonical address: POST /api/v1/actions/notifications.set_user_settings

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.settings_changed

What it writes: notification_user_setting (upsert) — Writes the person’s schedule

curl -X POST https://app.getera.io/api/v1/notification_user_settings/actions/set_user_settings \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"user_id":"USER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.settings_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationUserSettings.setUserSettings({
  user_id: "USER_ID"
})

era notification_user_settings set_user_settings \
  --user-id "USER_ID"

{
  "name": "era__notifications__set_user_settings",
  "arguments": {
    "user_id": "USER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_your_preference, not_a_member, invalid_timezone, invalid_quiet_hours · 429 slow down

notifications.settle_delivery

Record a delivery outcome — Marks a delivery done, or schedules the next attempt.

Needs notifications:handle · changes data

• Canonical address: POST /api/v1/actions/notifications.settle_delivery

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.delivered, notifications.delivery_failed

What it writes: notification_delivery (update) — Records the outcome and, on a retryable failure, when to try again; notification_channel (update) — Stamps verified_at the first time something reaches the channel

curl -X POST https://app.getera.io/api/v1/notification_deliveries/actions/settle_delivery \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"delivery_id":"DELIVERY_ID","success":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.delivered",
    "notifications.delivery_failed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationDeliveries.settleDelivery({
  delivery_id: "DELIVERY_ID",
  success: true
})

era notification_deliveries settle_delivery \
  --delivery-id "DELIVERY_ID" \
  --success true

{
  "name": "era__notifications__settle_delivery",
  "arguments": {
    "delivery_id": "DELIVERY_ID",
    "success": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 delivery_not_found, delivery_already_settled · 429 slow down

notifications.update_rule

Edit a notification rule — Changes a rule’s events, recipients, wording or quiet period.

Needs notifications:manage · changes data

• Canonical address: POST /api/v1/actions/notifications.update_rule

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: notifications.rule_updated

What it writes: notification_rule (update) — Rewrites the rule’s events, recipients and wording

curl -X POST https://app.getera.io/api/v1/notification_rules/NOTIFICATION_RULE_ID/actions/update_rule \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "notifications.rule_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.notificationRules.updateRule("NOTIFICATION_RULE_ID", {
  name: "Name"
})

era notification_rules update_rule NOTIFICATION_RULE_ID \
  --name "Name"

{
  "name": "era__notifications__update_rule",
  "arguments": {
    "rule_id": "NOTIFICATION_RULE_ID",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold notifications:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 rule_not_found, channel_not_found, name_taken, cooldown_out_of_range, recipient_incomplete · 429 slow down

Data models

NotificationChannel

Table notification_channel · Resource notification_channels

• GET /api/v1/notification_channels
• GET /api/v1/notification_channels/{id}

Primary key: id

Unique: workspace_id, type, name

NotificationDelivery

Table notification_delivery · Resource notification_deliveries

• GET /api/v1/notification_deliveries
• GET /api/v1/notification_deliveries/{id}

Primary key: id

Checks:

• CHECK (((attempts >= 0) AND (attempts <= 10)))
• CHECK (((medium <> 'channel'::text) OR (channel_id IS NOT NULL)))
• CHECK (((rule_id IS NOT NULL) OR is_test OR (payload ? 'to'::text) OR (payload ? 'customerId'::text)))
• CHECK (((response_status IS NULL) OR ((response_status >= 100) AND (response_status < 600))))
• CHECK (((state = 'suppressed'::os.notification_delivery_state) = (suppressed_reason IS NOT NULL)))

NotificationEmailTemplate

Table notification_email_template · Resource notification_email_templates

• GET /api/v1/notification_email_templates
• GET /api/v1/notification_email_templates/{id}

Primary key: id

Unique: workspace_id, kind

Checks:

• CHECK (((length(body) >= 1) AND (length(body) <= 20000)))
• CHECK (((length(subject) >= 1) AND (length(subject) <= 300)))

NotificationInbox

Table notification_inbox · Resource notification_inboxes

• GET /api/v1/notification_inboxes
• GET /api/v1/notification_inboxes/{id}

Primary key: id

NotificationPreference

Table notification_preference · Resource notification_preferences

• GET /api/v1/notification_preferences
• GET /api/v1/notification_preferences/{id}

Primary key: id

Unique: workspace_id, user_id, channel_type, event_name

NotificationRule

Table notification_rule · Resource notification_rules

• GET /api/v1/notification_rules
• GET /api/v1/notification_rules/{id}

Primary key: id

Unique: workspace_id, name

Checks:

• CHECK (((category = ''::text) OR (category ~ '^[a-z][a-z0-9_]{1,40}$'::text)))
• CHECK (((recipient = 'channel'::text) = (channel_id IS NOT NULL)))
• CHECK (((cooldown_minutes >= 0) AND (cooldown_minutes <= 10080)))
• CHECK ((mediums <@ ARRAY['in_app'::text, 'email'::text, 'sms'::text, 'whatsapp'::text]))

NotificationUserSetting

Table notification_user_setting · Resource notification_user_settings

• GET /api/v1/notification_user_settings
• GET /api/v1/notification_user_settings/{id}

Primary key: id

Unique: workspace_id, user_id

Checks:

• CHECK (((digest = ANY (ARRAY['off'::text, 'hourly'::text, 'daily'::text])) AND ((digest_hour >= 0) AND (digest_hour <= 23))))
• CHECK (((quiet_start IS NULL) = (quiet_end IS NULL)))

Events

Workflows and webhooks react to these events.