Node.js SDK

Setup & Initialization

  1. Install using one of the following package managers:
npm install pingram
yarn add pingram
pnpm add pingram
  1. Import:
import { Pingram } from 'pingram';
  1. Initialize:
const pingram = new Pingram({
apiKey: 'pingram_sk_...' // Your API key from the dashboard
});
Name Type Description
apiKey* string Your Pingram API key. You can get it from your dashboard under Environments.
accessToken string Optional JWT token for end-user authentication (for internal use)
baseURL string Optional. To choose a different region other than default (US). Use https://api.ca.pingram.io for the Canada region, and https://api.eu.pingram.io for the EU region.
  • required

Region specific example:

import { Pingram } from 'pingram';
const pingram = new Pingram({
apiKey: 'pingram_sk_...',
baseURL: 'https://api.eu.pingram.io'
});

Send

send()

Send a notification (email, SMS, etc.) to one user. Requires a notification `type` which categorizes this messages for future reporting, and channel-specific payloads such as `email` or `sms`. Recipient is specified with the `to` parameter. Returns a `trackingId` for error or delivery lookup through our Logs.

// Request body only
await pingram.send({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————— | ––––––– | ——————————— | — | | senderPostBody | SenderPostBody | See Request Body Properties below | |

Request Body Properties

Name Type Description
type string ID of the notification type (e.g. “welcome_email”). Creates a new notification if it does not exist.
to object Recipient user. Provide id, email, or number to identify the user.
to.id string Unique user identifier. Required.
to.email string User’s email address for email notifications.
to.number string User’s phone number for SMS/call notifications.
to.pushTokens object[] Mobile push tokens (FCM, APN) for push notifications.
to.pushTokens[].type “FCM” | “APN” (required)
to.pushTokens[].token string (required)
to.pushTokens[].device object (required)
to.pushTokens[].device.app_id string
to.pushTokens[].device.ad_id string
to.pushTokens[].device.device_id string (required)
to.pushTokens[].device.platform string
to.pushTokens[].device.manufacturer string
to.pushTokens[].device.model string
to.pushTokens[].environment string used by APN to differentiate between sandbox and production builds (sandbox/undefined or production)
to.webPushTokens object[] Web push subscription config from the browser.
to.webPushTokens[].sub object (required) Configuration for a Push Subscription. This can be obtained on the frontend by calling serviceWorkerRegistration.pushManager.subscribe(). The expected format is the same output as JSON.stringify’ing a PushSubscription in the browser.
to.webPushTokens[].sub.endpoint string (required)
to.webPushTokens[].sub.keys object (required)
to.webPushTokens[].sub.keys.p256dh string (required)
to.webPushTokens[].sub.keys.auth string (required)
to.timezone string User’s timezone (e.g. “America/New_York”) for scheduling.
to.slackChannel string The destination channel of slack notifications sent to this user. Can be either of the following: - Channel name, e.g. “test” - Channel name with # prefix, e.g. “#test” - Channel ID, e.g. “C1234567890” - User ID for DM, e.g. “U1234567890” - Username with @ prefix, e.g. “@test”
to.slackToken object
to.slackToken.access_token string
to.slackToken.app_id string
to.slackToken.authed_user object
to.slackToken.authed_user.access_token string
to.slackToken.authed_user.expires_in number
to.slackToken.authed_user.id string
to.slackToken.authed_user.refresh_token string
to.slackToken.authed_user.scope string
to.slackToken.authed_user.token_type string
to.slackToken.bot_user_id string
to.slackToken.enterprise object
to.slackToken.enterprise.id string
to.slackToken.enterprise.name string
to.slackToken.error string
to.slackToken.expires_in number
to.slackToken.incoming_webhook object
to.slackToken.incoming_webhook.channel string
to.slackToken.incoming_webhook.channel_id string
to.slackToken.incoming_webhook.configuration_url string
to.slackToken.incoming_webhook.url string
to.slackToken.is_enterprise_install boolean
to.slackToken.needed string
to.slackToken.ok boolean (required)
to.slackToken.provided string
to.slackToken.refresh_token string
to.slackToken.scope string
to.slackToken.team object
to.slackToken.team.id string
to.slackToken.team.name string
to.slackToken.token_type string
to.slackToken.warning string
to.slackToken.response_metadata object
to.slackToken.response_metadata.warnings string[]
to.slackToken.response_metadata.next_cursor string
to.slackToken.response_metadata.scopes string[]
to.slackToken.response_metadata.acceptedScopes string[]
to.slackToken.response_metadata.retryAfter number
to.slackToken.response_metadata.messages string[]
to.lastSeenTime string Last activity timestamp. Updated automatically. Read-only.
to.updatedAt string Last update timestamp. Read-only.
to.createdAt string Creation timestamp. Read-only.
to.emailSuppressionStatus object Bounce or complaint status if email was suppressed. Read-only.
to.emailSuppressionStatus.reason “Bounce” | “Complaint” (required)
to.emailSuppressionStatus.details object (required)
forceChannels (“EMAIL” | “INAPP_WEB” | “SMS” | “CALL” | “PUSH” | “WEB_PUSH” | “SLACK”)[] Override which channels to send to (e.g. [“EMAIL”, “SMS”]). Bypasses notification channel config.
parameters Record<string, any> Key-value pairs for template merge tags. Replaces placeholders like {{firstName}} in templates.
secondaryId string Optional sub-notification identifier for grouping or tracking.
templateId string Specific template ID to use. If omitted, uses the default template for each channel.
subNotificationId string Sub-notification identifier (e.g. for grouping related notifications).
options object Per-channel overrides for send options (email, APN, FCM).
options.email object Email-specific overrides.
options.email.replyToAddresses string[] Reply-to addresses for the email.
options.email.ccAddresses string[] CC recipients.
options.email.bccAddresses string[] BCC recipients.
options.email.fromAddress string Override sender email address.
options.email.fromName string Override sender display name.
options.email.attachments (object | object)[] File attachments (by URL or inline base64 content). Inline content: ~4 MB raw per file (413 if exceeded). URL url: up to 20 MB per file.
options.email.condition string Conditional expression for when to send (e.g. merge tag logic).
options.apn object Apple Push Notification (APN) overrides.
options.apn.expiry number Seconds until the notification expires.
options.apn.priority number Delivery priority (10 = immediate, 5 = power-saving).
options.apn.collapseId string Group notifications with the same ID (replaces previous).
options.apn.threadId string Thread identifier for grouping notifications.
options.apn.badge number Badge count on app icon.
options.apn.sound string Sound file name.
options.apn.contentAvailable boolean Silent background notification (no alert).
options.fcm object Firebase Cloud Messaging (FCM) overrides.
options.fcm.android object Android-specific FCM options.
options.fcm.android.collapseKey string Collapse key for grouping messages.
options.fcm.android.priority “high” | “normal” Delivery priority.
options.fcm.android.ttl number Time to live in seconds.
options.fcm.android.restrictedPackageName string Restrict delivery to a specific package.
options.push object Cross-platform mobile push options (applied to both APN and FCM).
options.push.customData Record<string, string> Up to 3 custom string key-value pairs for deep linking. Included in both APN and FCM payloads.
schedule string
email object Inline email content (subject, html). Use when not using templates.
email.subject string (required) Email subject line.
email.html string (required) HTML body content.
email.previewText string Preview/snippet text shown in inbox.
email.senderName string Display name of sender.
email.senderEmail string Sender email address.
inapp object Inline in-app content (title, url, image).
inapp.title string (required) Notification title.
inapp.url string URL to open when clicked.
inapp.image string Image URL.
sms object Inline SMS content (message, autoReply, from, mediaUrls).
sms.message string SMS/MMS body text.
sms.mediaUrls string[] Public HTTPS URLs of media to attach (MMS). Carriers fetch these via GET. Total size limits apply per provider.
sms.autoReply object
sms.autoReply.message string (required) Auto-reply message to send when user texts in.
sms.from string Override the sender phone number. Must be a verified number on your account.
call object Inline call content (message).
call.message string (required) Text to speak (TTS).
web_push object Inline web push content (title, message, icon, url).
web_push.title string (required) Notification title.
web_push.message string (required) Body text.
web_push.icon string Icon URL.
web_push.url string URL to open when clicked.
mobile_push object Inline mobile push content (title, message).
mobile_push.title string (required) Notification title.
mobile_push.message string (required) Body text.
slack object Inline Slack content (text, blocks, etc.).
slack.text string (required) Fallback plain text (required when using blocks).
slack.blocks Record<string, any>[] Slack Block Kit blocks.
slack.username string Override bot username.
slack.icon string Icon: emoji (e.g. “:smile:”) or URL. Default: bot’s icon.
slack.thread_ts string Parent message ts to post in a thread.
slack.reply_broadcast boolean When true with thread_ts, broadcasts reply to channel. Default: false.
slack.parse “full” | “none” URL parsing: “full” (clickable links) or “none”. Default: “none”.
slack.link_names boolean Convert channel and username refs to Slack links. Default: false.
slack.mrkdwn boolean Enable Slack markup (bold, italic, code). Default: true.
slack.unfurl_links boolean Unfurl link previews. Default: true.
slack.unfurl_media boolean Unfurl media previews. Default: true.
slack.metadata object Slack message metadata with optional work object entities. Combines standard Slack message metadata fields with an array of entity objects.
slack.metadata.entities object[] An array of work object entities.
slack.metadata.entities[].entity_type string (required) Entity type (e.g., ‘slack#/entities/task’, ‘slack#/entities/file’).
slack.metadata.entities[].entity_payload Record<string, any> (required) Schema for the given entity type.
slack.metadata.entities[].external_ref object (required) Reference used to identify an entity within the developer’s system.
slack.metadata.entities[].external_ref.id string (required)
slack.metadata.entities[].external_ref.type string
slack.metadata.entities[].url string (required) URL used to identify an entity within the developer’s system.
slack.metadata.entities[].app_unfurl_url string The exact URL posted in the source message. Required in metadata passed to chat.unfurl.
slack.metadata.event_type string A human readable alphanumeric string representing your application’s metadata event.
slack.metadata.event_payload Record<string, any> A free-form object containing whatever data your application wishes to attach to messages.

Webhooks

deleteEventsWebhook()

Delete the events webhook configuration for the current account/environment.

// No parameters
await pingram.webhooks.deleteEventsWebhook();

Parameters

This endpoint does not need any parameter.

getEventsWebhook()

Get the events webhook configuration for the current account/environment.

// No parameters
await pingram.webhooks.getEventsWebhook();

Parameters

This endpoint does not need any parameter.

upsertEventsWebhook()

Create or update the events webhook configuration for the current account/environment.

// Request body only
await pingram.webhooks.upsertEventsWebhook({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————————— | ––––––––––––– | ——————————— | — | | eventsWebhookUpsertRequest | EventsWebhookUpsertRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
webhook string (required) Destination URL that receives webhook event payloads. Must be a valid http(s) URL.
events (“EMAIL_OPEN” | “EMAIL_CLICK” | “EMAIL_FAILED” | “EMAIL_DELIVERED” | “EMAIL_UNSUBSCRIBE” | “EMAIL_INBOUND” | “INAPP_WEB_FAILED” | “INAPP_WEB_UNSUBSCRIBE” | “SMS_DELIVERED” | “SMS_FAILED” | “SMS_UNSUBSCRIBE” | “SMS_SUBSCRIBE” | “SMS_INBOUND” | “PUSH_FAILED” | “PUSH_UNSUBSCRIBE” | “CALL_FAILED” | “CALL_UNSUBSCRIBE” | “WEB_PUSH_FAILED” | “WEB_PUSH_UNSUBSCRIBE” | “SLACK_FAILED” | “SLACK_UNSUBSCRIBE” | “VOICE_INBOUND”)[] (required) List of event types that should be forwarded to the webhook URL.

Addresses

createAddress()

Create a new email inbox. Omit `domain` for a built-in `@mail.pingram.io` address; set `domain` and `displayName` for a custom address on a verified domain.

// Request body only
await pingram.addresses.createAddress({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ———————— | –––––––––– | ——————————— | — | | createAddressRequest | CreateAddressRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
prefix string (required)
domain string
displayName string

deleteAddress()

Delete a custom inbound address. Builtin addresses cannot be deleted.

// Path parameter only
await pingram.addresses.deleteAddress('fullAddress_example');

Parameters

Name Type Description
fullAddress string Full address to delete (e.g. hello@example.com)

listAddresses()

List email inboxes (addresses) configured for receiving. Custom addresses must use a verified domain.

// No parameters
await pingram.addresses.listAddresses();

Parameters

This endpoint does not need any parameter.

updateAddress()

Update an inbox prefix or display name.

// Request body only
await pingram.addresses.updateAddress({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ———————— | –––––––––– | ——————————— | — | | updateAddressRequest | UpdateAddressRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
fullAddress string (required)
prefix string
displayName string

Domains

addDomain()

Add and start verification for a new sender domain. Pass the domain only (not a full email address).

// Request body only
await pingram.domains.addDomain({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ––––––––––––– | ––––––––––– | ——————————— | — | | postSendersRequestBody | PostSendersRequestBody | See Request Body Properties below | |

Request Body Properties

Name Type Description
sender string (required)

deleteDomain()

Remove a sender domain from the account.

// Path parameter only
await pingram.domains.deleteDomain('sender_example');

Parameters

Name Type Description
sender string Sender domain (URL encoded)

listDomains()

List sender domains configured for the account (for outbound email).

// No parameters
await pingram.domains.listDomains();

Parameters

This endpoint does not need any parameter.

startDomainVerification()

Start SES domain verification (DNS readiness is checked client-side via checkDomainDns)

// Path parameter only
await pingram.domains.startDomainVerification('sender_example');

Parameters

Name Type Description
sender string Sender domain (URL encoded)

Email

send()

Send an email. Requires `type`, `to`, `subject`, and `html`. Optional: `fromAddress`, `fromName`, `schedule`, attachments. The fromAddress must be a verified domain; otherwise our built-in address will be used which is fine for testing purposes.

// Request body only
await pingram.email.send({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | –––––––––– | –––––––– | ——————————— | — | | sendEmailRequest | SendEmailRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
type string (required) The notification type to send.
to string (required) The email address of the recipient.
subject string (required) The subject of the email.
html string (required) The HTML body of the email.
fromName string The display name of the sender.
fromAddress string The email address of the sender.
previewText string The preview text of the email.
replyToAddresses string[] The reply-to addresses of the email.
ccAddresses string[] The CC addresses of the email.
bccAddresses string[] The BCC addresses of the email.
attachments object[] URL-based file attachments. Up to 20 MB per file.
attachments[].filename string (required)
attachments[].url string (required)
schedule string The ISO 8601 datetime to schedule the email.

Environments

createEnvironment()

Create a new environment for the account

// Request body only
await pingram.environments.createEnvironment({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | –––––––––––––– | ———————— | ——————————— | — | | environmentCreateRequest | EnvironmentCreateRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
title string (required)

listEnvironments()

Get all environments for the authenticated account

// No parameters
await pingram.environments.listEnvironments();

Parameters

This endpoint does not need any parameter.

updateEnvironment()

Update environment settings (title, secret, disable sending, secure mode)

// Path parameter + request body
await pingram.environments.updateEnvironment('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ————————— | ———————– | ——————————— | — | | clientId | string | Environment client ID | | environmentPatchRequest | EnvironmentPatchRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
resetSecret boolean
disableSending (“EMAIL” | “INAPP_WEB” | “SMS” | “CALL” | “PUSH” | “WEB_PUSH” | “SLACK”)[]
title string
secureMode boolean

Logs

getLogRetention()

Get log retention period in days for the account

// No parameters
await pingram.logs.getLogRetention();

Parameters

This endpoint does not need any parameter.

getLogs()

List recent notification logs for the authenticated account, newest first.

// No parameters
await pingram.logs.getLogs();

Parameters

Name Type Description
limit number Maximum number of logs to return (default
cursor string Pagination cursor for next page

getLogsByTrackingIds()

Get logs by tracking IDs (comma-separated, max 25 IDs). Use after sending email or SMS to look up delivery status.

// Path parameter only
await pingram.logs.getLogsByTrackingIds('trackingIds_example');

Parameters

Name Type Description
trackingIds string Comma-separated tracking IDs (URL encoded)

getLogsQueryResult()

Get results from a log query started with Start Log Query. Poll until status is Complete.

// Path parameter only
await pingram.logs.getLogsQueryResult('queryId_example');

Parameters

Name Type Description
queryId string Query ID returned by Start Log Query

startLogsQuery()

Start an asynchronous log search over a date range. Returns a `queryId`; poll with Get Log Query Results until status is Complete.

// Request body only
await pingram.logs.startLogsQuery({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | –––––––––– | –––––––– | ——————————— | — | | logQueryPostBody | LogQueryPostBody | See Request Body Properties below | |

Request Body Properties

Name Type Description
dateRangeFilter number[] A tuple of [startTime, endTime] for the date range filter, each representing a unix timestamp.
userFilter string
envIdFilter string[]
statusFilter string
channelFilter (“email” | “inapp” | “sms” | “call” | “web_push” | “mobile_push” | “slack”)[]
notificationFilter string[]

tailLogs()

Get last 100 logs from the stream

// No parameters
await pingram.logs.tailLogs();

Parameters

This endpoint does not need any parameter.

Numbers

list()

List active phone numbers registered for the account.

// No parameters
await pingram.numbers.list();

Parameters

This endpoint does not need any parameter.

listReleased()

List released phone numbers. Released numbers may be purchased again with 2 weeks of being released. Released numbers may be removed from released list after 2 weeks.

// No parameters
await pingram.numbers.listReleased();

Parameters

This endpoint does not need any parameter.

orderNumber()

Purchase a phone number for the authenticated account, or reactivate a released number owned by the account (preserves original createdAt). Pass `phoneNumber` in E.164 format (e.g. +15551234567).

// Request body only
await pingram.numbers.orderNumber({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ————————— | ———————– | ——————————— | — | | orderPhoneNumberRequest | OrderPhoneNumberRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
phoneNumber string (required) E.164 from search results

releaseNumber()

Release a phone number from the account. No refund for the current billing month.

// Path parameter only
await pingram.numbers.releaseNumber('phoneNumber_example');

Parameters

Name Type Description
phoneNumber string E.164 phone number to release

searchAvailable()

Search for available phone numbers to purchase. Requires `countryCode` (e.g. US, CA). Use before ordering a number.

// No parameters
await pingram.numbers.searchAvailable();

Parameters

Name Type Description
countryCode string ISO 3166-1 alpha-2 country code (e.g., US, CA)
features string Comma-separated
areaCode string National destination / area code filter
limit number Max results (default 10, max 50)

Organization

create()

Create organization after SMS verification bypass

// No parameters
await pingram.organization.create();

Parameters

This endpoint does not need any parameter.

getUsage()

Get usage for the authenticated account&#39;s organization (new billing model).

// No parameters
await pingram.organization.getUsage();

Parameters

This endpoint does not need any parameter.

getUsageHistory()

Get historical usage for the authenticated account&#39;s organization over a date range.

// No parameters
await pingram.organization.getUsageHistory();

Parameters

Name Type Description
startDate string Start date (YYYY-MM-DD) for the range
endDate string End date (YYYY-MM-DD) for the range

Profile

acceptInvite()

Accept a team invitation using a token

// Request body only
await pingram.profile.acceptInvite({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ———————– | —————–– | ——————————— | — | | acceptInviteRequest | AcceptInviteRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
token string (required)

changeEmail()

Change the email address of the authenticated user

// Request body only
await pingram.profile.changeEmail({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ––––––––––– | —————— | ——————————— | — | | changeEmailRequest | ChangeEmailRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
newEmail string (required)

deleteAccount()

Permanently delete the authenticated user&#39;s account

// Request body only
await pingram.profile.deleteAccount({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ———————— | –––––––––– | ——————————— | — | | deleteAccountRequest | DeleteAccountRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
reason string

disableMfa()

Disable MFA for the authenticated user

// Path parameter only
await pingram.profile.disableMfa('type_example');

Parameters

Name Type Description
type string MFA type (e.g. SOFTWARE_TOKEN_MFA)

getMfaStatus()

Get MFA status for the authenticated user

// No parameters
await pingram.profile.getMfaStatus();

Parameters

This endpoint does not need any parameter.

setupMfa()

Start TOTP MFA setup and return QR code data

// Request body only
await pingram.profile.setupMfa({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————–– | ————— | ——————————— | — | | mFASetupRequest | MFASetupRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
type “SOFTWARE_TOKEN_MFA” (required) MFA methods supported by the profile MFA API.

verifyMfa()

Verify TOTP code and enable MFA

// Request body only
await pingram.profile.verifyMfa({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | –––––––––– | –––––––– | ——————————— | — | | mFAVerifyRequest | MFAVerifyRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
type “SOFTWARE_TOKEN_MFA” (required) MFA methods supported by the profile MFA API.
code string (required)
session string (required)

PushSettings

deletePushApnSettings()

Delete Apple Push Notification (APN) configuration for the current account.

// No parameters
await pingram.pushSettings.deletePushApnSettings();

Parameters

This endpoint does not need any parameter.

deletePushFcmSettings()

Delete Firebase Cloud Messaging (FCM) configuration for the current account.

// No parameters
await pingram.pushSettings.deletePushFcmSettings();

Parameters

This endpoint does not need any parameter.

getPushApnSettings()

Get Apple Push Notification (APN) configuration for the current account.

// No parameters
await pingram.pushSettings.getPushApnSettings();

Parameters

This endpoint does not need any parameter.

getPushFcmSettings()

Get Firebase Cloud Messaging (FCM) configuration for the current account.

// No parameters
await pingram.pushSettings.getPushFcmSettings();

Parameters

This endpoint does not need any parameter.

upsertPushApnSettings()

Create or update Apple Push Notification (APN) configuration for the current account.

// Request body only
await pingram.pushSettings.upsertPushApnSettings({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ———–– | ——— | ——————————— | — | | aPNConfig | APNConfig | See Request Body Properties below | |

Request Body Properties

Name Type Description
KeyId string (required)
Key string (required)
TeamId string (required)
Topic string (required)

upsertPushFcmSettings()

Create or update Firebase Cloud Messaging (FCM) configuration for the current account.

// Request body only
await pingram.pushSettings.upsertPushFcmSettings({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————————– | ———————–– | ——————————— | — | | pushSettingsFCMPutRequest | PushSettingsFCMPutRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
fcmConfig string (required)

Sender

deleteSchedule()

Delete (unschedule) an already scheduled notification

// Path parameter only
await pingram.sender.deleteSchedule('trackingId_example');

Parameters

Name Type Description
trackingId string The tracking ID of the scheduled notification

updateSchedule()

Update the body or schedule of an already scheduled notification.

// Path parameter + request body
await pingram.sender.updateSchedule('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————— | ––––––– | ——————————————— | — | | trackingId | string | The tracking ID of the scheduled notification | | senderPostBody | SenderPostBody | See Request Body Properties below | |

Request Body Properties

Name Type Description
type string ID of the notification type (e.g. “welcome_email”). Creates a new notification if it does not exist.
to object Recipient user. Provide id, email, or number to identify the user.
to.id string Unique user identifier. Required.
to.email string User’s email address for email notifications.
to.number string User’s phone number for SMS/call notifications.
to.pushTokens object[] Mobile push tokens (FCM, APN) for push notifications.
to.pushTokens[].type “FCM” | “APN” (required)
to.pushTokens[].token string (required)
to.pushTokens[].device object (required)
to.pushTokens[].device.app_id string
to.pushTokens[].device.ad_id string
to.pushTokens[].device.device_id string (required)
to.pushTokens[].device.platform string
to.pushTokens[].device.manufacturer string
to.pushTokens[].device.model string
to.pushTokens[].environment string used by APN to differentiate between sandbox and production builds (sandbox/undefined or production)
to.webPushTokens object[] Web push subscription config from the browser.
to.webPushTokens[].sub object (required) Configuration for a Push Subscription. This can be obtained on the frontend by calling serviceWorkerRegistration.pushManager.subscribe(). The expected format is the same output as JSON.stringify’ing a PushSubscription in the browser.
to.webPushTokens[].sub.endpoint string (required)
to.webPushTokens[].sub.keys object (required)
to.webPushTokens[].sub.keys.p256dh string (required)
to.webPushTokens[].sub.keys.auth string (required)
to.timezone string User’s timezone (e.g. “America/New_York”) for scheduling.
to.slackChannel string The destination channel of slack notifications sent to this user. Can be either of the following: - Channel name, e.g. “test” - Channel name with # prefix, e.g. “#test” - Channel ID, e.g. “C1234567890” - User ID for DM, e.g. “U1234567890” - Username with @ prefix, e.g. “@test”
to.slackToken object
to.slackToken.access_token string
to.slackToken.app_id string
to.slackToken.authed_user object
to.slackToken.authed_user.access_token string
to.slackToken.authed_user.expires_in number
to.slackToken.authed_user.id string
to.slackToken.authed_user.refresh_token string
to.slackToken.authed_user.scope string
to.slackToken.authed_user.token_type string
to.slackToken.bot_user_id string
to.slackToken.enterprise object
to.slackToken.enterprise.id string
to.slackToken.enterprise.name string
to.slackToken.error string
to.slackToken.expires_in number
to.slackToken.incoming_webhook object
to.slackToken.incoming_webhook.channel string
to.slackToken.incoming_webhook.channel_id string
to.slackToken.incoming_webhook.configuration_url string
to.slackToken.incoming_webhook.url string
to.slackToken.is_enterprise_install boolean
to.slackToken.needed string
to.slackToken.ok boolean (required)
to.slackToken.provided string
to.slackToken.refresh_token string
to.slackToken.scope string
to.slackToken.team object
to.slackToken.team.id string
to.slackToken.team.name string
to.slackToken.token_type string
to.slackToken.warning string
to.slackToken.response_metadata object
to.slackToken.response_metadata.warnings string[]
to.slackToken.response_metadata.next_cursor string
to.slackToken.response_metadata.scopes string[]
to.slackToken.response_metadata.acceptedScopes string[]
to.slackToken.response_metadata.retryAfter number
to.slackToken.response_metadata.messages string[]
to.lastSeenTime string Last activity timestamp. Updated automatically. Read-only.
to.updatedAt string Last update timestamp. Read-only.
to.createdAt string Creation timestamp. Read-only.
to.emailSuppressionStatus object Bounce or complaint status if email was suppressed. Read-only.
to.emailSuppressionStatus.reason “Bounce” | “Complaint” (required)
to.emailSuppressionStatus.details object (required)
forceChannels (“EMAIL” | “INAPP_WEB” | “SMS” | “CALL” | “PUSH” | “WEB_PUSH” | “SLACK”)[] Override which channels to send to (e.g. [“EMAIL”, “SMS”]). Bypasses notification channel config.
parameters Record<string, any> Key-value pairs for template merge tags. Replaces placeholders like {{firstName}} in templates.
secondaryId string Optional sub-notification identifier for grouping or tracking.
templateId string Specific template ID to use. If omitted, uses the default template for each channel.
subNotificationId string Sub-notification identifier (e.g. for grouping related notifications).
options object Per-channel overrides for send options (email, APN, FCM).
options.email object Email-specific overrides.
options.email.replyToAddresses string[] Reply-to addresses for the email.
options.email.ccAddresses string[] CC recipients.
options.email.bccAddresses string[] BCC recipients.
options.email.fromAddress string Override sender email address.
options.email.fromName string Override sender display name.
options.email.attachments (object | object)[] File attachments (by URL or inline base64 content). Inline content: ~4 MB raw per file (413 if exceeded). URL url: up to 20 MB per file.
options.email.condition string Conditional expression for when to send (e.g. merge tag logic).
options.apn object Apple Push Notification (APN) overrides.
options.apn.expiry number Seconds until the notification expires.
options.apn.priority number Delivery priority (10 = immediate, 5 = power-saving).
options.apn.collapseId string Group notifications with the same ID (replaces previous).
options.apn.threadId string Thread identifier for grouping notifications.
options.apn.badge number Badge count on app icon.
options.apn.sound string Sound file name.
options.apn.contentAvailable boolean Silent background notification (no alert).
options.fcm object Firebase Cloud Messaging (FCM) overrides.
options.fcm.android object Android-specific FCM options.
options.fcm.android.collapseKey string Collapse key for grouping messages.
options.fcm.android.priority “high” | “normal” Delivery priority.
options.fcm.android.ttl number Time to live in seconds.
options.fcm.android.restrictedPackageName string Restrict delivery to a specific package.
options.push object Cross-platform mobile push options (applied to both APN and FCM).
options.push.customData Record<string, string> Up to 3 custom string key-value pairs for deep linking. Included in both APN and FCM payloads.
schedule string
email object Inline email content (subject, html). Use when not using templates.
email.subject string (required) Email subject line.
email.html string (required) HTML body content.
email.previewText string Preview/snippet text shown in inbox.
email.senderName string Display name of sender.
email.senderEmail string Sender email address.
inapp object Inline in-app content (title, url, image).
inapp.title string (required) Notification title.
inapp.url string URL to open when clicked.
inapp.image string Image URL.
sms object Inline SMS content (message, autoReply, from, mediaUrls).
sms.message string SMS/MMS body text.
sms.mediaUrls string[] Public HTTPS URLs of media to attach (MMS). Carriers fetch these via GET. Total size limits apply per provider.
sms.autoReply object
sms.autoReply.message string (required) Auto-reply message to send when user texts in.
sms.from string Override the sender phone number. Must be a verified number on your account.
call object Inline call content (message).
call.message string (required) Text to speak (TTS).
web_push object Inline web push content (title, message, icon, url).
web_push.title string (required) Notification title.
web_push.message string (required) Body text.
web_push.icon string Icon URL.
web_push.url string URL to open when clicked.
mobile_push object Inline mobile push content (title, message).
mobile_push.title string (required) Notification title.
mobile_push.message string (required) Body text.
slack object Inline Slack content (text, blocks, etc.).
slack.text string (required) Fallback plain text (required when using blocks).
slack.blocks Record<string, any>[] Slack Block Kit blocks.
slack.username string Override bot username.
slack.icon string Icon: emoji (e.g. “:smile:”) or URL. Default: bot’s icon.
slack.thread_ts string Parent message ts to post in a thread.
slack.reply_broadcast boolean When true with thread_ts, broadcasts reply to channel. Default: false.
slack.parse “full” | “none” URL parsing: “full” (clickable links) or “none”. Default: “none”.
slack.link_names boolean Convert channel and username refs to Slack links. Default: false.
slack.mrkdwn boolean Enable Slack markup (bold, italic, code). Default: true.
slack.unfurl_links boolean Unfurl link previews. Default: true.
slack.unfurl_media boolean Unfurl media previews. Default: true.
slack.metadata object Slack message metadata with optional work object entities. Combines standard Slack message metadata fields with an array of entity objects.
slack.metadata.entities object[] An array of work object entities.
slack.metadata.entities[].entity_type string (required) Entity type (e.g., ‘slack#/entities/task’, ‘slack#/entities/file’).
slack.metadata.entities[].entity_payload Record<string, any> (required) Schema for the given entity type.
slack.metadata.entities[].external_ref object (required) Reference used to identify an entity within the developer’s system.
slack.metadata.entities[].external_ref.id string (required)
slack.metadata.entities[].external_ref.type string
slack.metadata.entities[].url string (required) URL used to identify an entity within the developer’s system.
slack.metadata.entities[].app_unfurl_url string The exact URL posted in the source message. Required in metadata passed to chat.unfurl.
slack.metadata.event_type string A human readable alphanumeric string representing your application’s metadata event.
slack.metadata.event_payload Record<string, any> A free-form object containing whatever data your application wishes to attach to messages.

Sms

send()

Send an SMS or MMS directly without a template. Requires `type` and `to`. Pass `message` and/or `mediaUrls`. Optional: `from`, `schedule`.

// Request body only
await pingram.sms.send({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————— | ––––––– | ——————————— | — | | sendSmsRequest | SendSmsRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
type string (required) The notification type to send.
to string (required) The phone number of the recipient.
message string The message of the SMS or MMS notification. Optional when mediaUrls is provided.
mediaUrls string[] Public HTTPS URLs of media to attach (MMS).
schedule string The ISO 8601 datetime to schedule the SMS notification.
from string Override the sender phone number. Must be a dedicated number on your Pingram account.

Templates

createTemplate()

Create a new template for a notification

// Path parameter + request body
await pingram.templates.createTemplate('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ———————– | —————–– | ——————————— | — | | notificationId | string | Notification ID | | channel | string | Channel type | | templatePostRequest | TemplatePostRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
templateId string (required) Unique ID for this template within the notification and channel. Required.
html string HTML body of the email.
previewText string Preview text (e.g. for inbox).
internal string Internal editor representation of the email content (e.g. Bee or Redactor JSON). Used for editing and component embedding; the actual email sent to recipients uses the html field.
subject string Email subject line.
senderName string Sender display name.
senderEmail string Sender email address.
title string Notification title (in-app).
redirectURL string URL to open when the user taps the notification.
imageURL string Image URL shown in the in-app notification.
instant object Copy for instant (real-time) delivery.
instant.title string
instant.redirectURL string
instant.imageURL string (required)
batch object Copy for batch delivery.
batch.title string (required)
batch.redirectURL string (required)
batch.imageURL string (required)
text string Message text (SMS or call).
message string Push notification body text. (title is shared with INAPP_WEB above.)
icon string Web push: icon URL. Slack: bot icon (emoji or URL).
url string Web push: URL to open when the notification is clicked.
blocks Record<string, any>[] Slack message blocks (optional).
username string Slack bot username.

deleteTemplate()

Delete a template

// Path parameter only
await pingram.templates.deleteTemplate('notificationId_example');

Parameters

Name Type Description
notificationId string Notification ID
channel string Channel type
templateId string Template ID

getTemplate()

Get a single template by ID

// Path parameter only
await pingram.templates.getTemplate('notificationId_example');

Parameters

Name Type Description
notificationId string Notification ID
channel string Channel type
templateId string Template ID

listTemplates()

List all templates for a notification and channel

// Path parameter only
await pingram.templates.listTemplates('notificationId_example');

Parameters

Name Type Description
notificationId string Notification ID
channel string Channel type

setDefaultTemplate()

Set a template as default for specific delivery modes

// Path parameter + request body
await pingram.templates.setDefaultTemplate('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————————– | ———————–– | ——————————— | — | | notificationId | string | Notification ID | | channel | string | Channel type | | setDefaultTemplateRequest | SetDefaultTemplateRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
templateId string (required)
modes (“instant” | “hourly” | “daily” | “weekly” | “monthly”)[] (required)

updateTemplate()

Update a template&#39;s properties

// Path parameter + request body
await pingram.templates.updateTemplate('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ———————— | –––––––––– | ——————————— | — | | notificationId | string | Notification ID | | channel | string | Channel type | | templateId | string | Template ID | | templatePatchRequest | TemplatePatchRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
html string HTML body of the email.
previewText string Preview text (e.g. for inbox).
internal string Internal editor representation of the email content (e.g. Bee or Redactor JSON). Used for editing and component embedding; the actual email sent to recipients uses the html field.
subject string Email subject line.
senderName string Sender display name.
senderEmail string Sender email address.
title string Notification title (in-app).
redirectURL string URL to open when the user taps the notification.
imageURL string Image URL shown in the in-app notification.
instant object Copy for instant (real-time) delivery.
instant.title string
instant.redirectURL string
instant.imageURL string (required)
batch object Copy for batch delivery.
batch.title string (required)
batch.redirectURL string (required)
batch.imageURL string (required)
text string Message text (SMS or call).
message string Push notification body text. (title is shared with INAPP_WEB above.)
icon string Web push: icon URL. Slack: bot icon (emoji or URL).
url string Web push: URL to open when the notification is clicked.
blocks Record<string, any>[] Slack message blocks (optional).
username string Slack bot username.

Types

createNotificationType()

Create a new notification

// Request body only
await pingram.types.createNotificationType({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————————– | ———————–– | ——————————— | — | | notificationCreateRequest | NotificationCreateRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
notificationId string (required)
title string (required)
channels string[] (required)
options object
options.EMAIL object
options.EMAIL.defaultDeliveryOption “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” (required)
options.EMAIL.off object
options.EMAIL.off.enabled boolean (required)
options.EMAIL.instant object
options.EMAIL.instant.enabled boolean (required)
options.EMAIL.hourly object
options.EMAIL.hourly.enabled boolean (required)
options.EMAIL.daily object
options.EMAIL.daily.enabled boolean (required)
options.EMAIL.daily.hour string
options.EMAIL.weekly object
options.EMAIL.weekly.enabled boolean (required)
options.EMAIL.weekly.hour string
options.EMAIL.weekly.day string
options.EMAIL.monthly object
options.EMAIL.monthly.enabled boolean (required)
options.EMAIL.monthly.hour string
options.EMAIL.monthly.date “first” | “last”
options.INAPP_WEB object
options.INAPP_WEB.defaultDeliveryOption “off” | “instant” (required)
options.INAPP_WEB.off object
options.INAPP_WEB.off.enabled boolean (required)
options.INAPP_WEB.instant object
options.INAPP_WEB.instant.enabled boolean (required)
options.INAPP_WEB.instant.batching boolean
options.INAPP_WEB.instant.batchingKey string
options.INAPP_WEB.instant.batchingWindow number
options.SMS object
options.SMS.defaultDeliveryOption “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” (required)
options.SMS.off object
options.SMS.off.enabled boolean (required)
options.SMS.instant object
options.SMS.instant.enabled boolean (required)
options.SMS.hourly object
options.SMS.hourly.enabled boolean (required)
options.SMS.daily object
options.SMS.daily.enabled boolean (required)
options.SMS.daily.hour string
options.SMS.weekly object
options.SMS.weekly.enabled boolean (required)
options.SMS.weekly.hour string
options.SMS.weekly.day string
options.SMS.monthly object
options.SMS.monthly.enabled boolean (required)
options.SMS.monthly.hour string
options.SMS.monthly.date “first” | “last”
options.CALL object
options.CALL.defaultDeliveryOption “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” (required)
options.CALL.off object
options.CALL.off.enabled boolean (required)
options.CALL.instant object
options.CALL.instant.enabled boolean (required)
options.CALL.hourly object
options.CALL.hourly.enabled boolean (required)
options.CALL.daily object
options.CALL.daily.enabled boolean (required)
options.CALL.daily.hour string
options.CALL.weekly object
options.CALL.weekly.enabled boolean (required)
options.CALL.weekly.hour string
options.CALL.weekly.day string
options.CALL.monthly object
options.CALL.monthly.enabled boolean (required)
options.CALL.monthly.hour string
options.CALL.monthly.date “first” | “last”
options.PUSH object
options.PUSH.defaultDeliveryOption “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” (required)
options.PUSH.off object
options.PUSH.off.enabled boolean (required)
options.PUSH.instant object
options.PUSH.instant.enabled boolean (required)
options.PUSH.hourly object
options.PUSH.hourly.enabled boolean (required)
options.PUSH.daily object
options.PUSH.daily.enabled boolean (required)
options.PUSH.daily.hour string
options.PUSH.weekly object
options.PUSH.weekly.enabled boolean (required)
options.PUSH.weekly.hour string
options.PUSH.weekly.day string
options.PUSH.monthly object
options.PUSH.monthly.enabled boolean (required)
options.PUSH.monthly.hour string
options.PUSH.monthly.date “first” | “last”
options.WEB_PUSH object
options.WEB_PUSH.defaultDeliveryOption “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” (required)
options.WEB_PUSH.off object
options.WEB_PUSH.off.enabled boolean (required)
options.WEB_PUSH.instant object
options.WEB_PUSH.instant.enabled boolean (required)
options.WEB_PUSH.hourly object
options.WEB_PUSH.hourly.enabled boolean (required)
options.WEB_PUSH.daily object
options.WEB_PUSH.daily.enabled boolean (required)
options.WEB_PUSH.daily.hour string
options.WEB_PUSH.weekly object
options.WEB_PUSH.weekly.enabled boolean (required)
options.WEB_PUSH.weekly.hour string
options.WEB_PUSH.weekly.day string
options.WEB_PUSH.monthly object
options.WEB_PUSH.monthly.enabled boolean (required)
options.WEB_PUSH.monthly.hour string
options.WEB_PUSH.monthly.date “first” | “last”
options.SLACK object
options.SLACK.defaultDeliveryOption “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” (required)
options.SLACK.off object
options.SLACK.off.enabled boolean (required)
options.SLACK.instant object
options.SLACK.instant.enabled boolean (required)
options.SLACK.hourly object
options.SLACK.hourly.enabled boolean (required)
options.SLACK.daily object
options.SLACK.daily.enabled boolean (required)
options.SLACK.daily.hour string
options.SLACK.weekly object
options.SLACK.weekly.enabled boolean (required)
options.SLACK.weekly.hour string
options.SLACK.weekly.day string
options.SLACK.monthly object
options.SLACK.monthly.enabled boolean (required)
options.SLACK.monthly.hour string
options.SLACK.monthly.date “first” | “last”

deleteNotificationType()

Delete a notification

// Path parameter only
await pingram.types.deleteNotificationType('notificationId_example');

Parameters

Name Type Description
notificationId string The notification ID

getNotificationType()

Get a specific notification by ID

// Path parameter only
await pingram.types.getNotificationType('notificationId_example');

Parameters

Name Type Description
notificationId string The notification ID

listNotificationTypes()

Get all notifications for an account with their templates

// No parameters
await pingram.types.listNotificationTypes();

Parameters

This endpoint does not need any parameter.

updateNotificationType()

Update a notification&#39;s settings

// Path parameter + request body
await pingram.types.updateNotificationType('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | –––––––––––––– | ———————— | ——————————— | — | | notificationId | string | The notification ID | | notificationPatchRequest | NotificationPatchRequest | See Request Body Properties below | |

Request Body Properties

| Name | Type | Description | | —————————————— | –––––––––––––––––––––––––––––––––––––––– | ———– | — | | title | string | | | channels | (“EMAIL” | “INAPP_WEB” | “SMS” | “CALL” | “PUSH” | “WEB_PUSH” | “SLACK”)[] | | | enabled | boolean | | | deduplication | object | | | deduplication.duration | number | (required) | | throttling | object | | | throttling.max | number | (required) | | throttling.period | number | (required) | | throttling.unit | “seconds” | “minutes” | “hours” | “days” | “months” | “years” | (required) | | throttling.forever | boolean | (required) | | throttling.scope | (“userId” | “notificationId”)[] | (required) | | retention | number | null | | | options | object | | | options.EMAIL | object | | | options.EMAIL.defaultDeliveryOption | “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” | (required) | | options.EMAIL.off | object | | | options.EMAIL.off.enabled | boolean | (required) | | options.EMAIL.instant | object | | | options.EMAIL.instant.enabled | boolean | (required) | | options.EMAIL.hourly | object | | | options.EMAIL.hourly.enabled | boolean | (required) | | options.EMAIL.daily | object | | | options.EMAIL.daily.enabled | boolean | (required) | | options.EMAIL.daily.hour | string | | | options.EMAIL.weekly | object | | | options.EMAIL.weekly.enabled | boolean | (required) | | options.EMAIL.weekly.hour | string | | | options.EMAIL.weekly.day | string | | | options.EMAIL.monthly | object | | | options.EMAIL.monthly.enabled | boolean | (required) | | options.EMAIL.monthly.hour | string | | | options.EMAIL.monthly.date | “first” | “last” | | | options.INAPP_WEB | object | | | options.INAPP_WEB.defaultDeliveryOption | “off” | “instant” | (required) | | options.INAPP_WEB.off | object | | | options.INAPP_WEB.off.enabled | boolean | (required) | | options.INAPP_WEB.instant | object | | | options.INAPP_WEB.instant.enabled | boolean | (required) | | options.INAPP_WEB.instant.batching | boolean | | | options.INAPP_WEB.instant.batchingKey | string | | | options.INAPP_WEB.instant.batchingWindow | number | | | options.SMS | object | | | options.SMS.defaultDeliveryOption | “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” | (required) | | options.SMS.off | object | | | options.SMS.off.enabled | boolean | (required) | | options.SMS.instant | object | | | options.SMS.instant.enabled | boolean | (required) | | options.SMS.hourly | object | | | options.SMS.hourly.enabled | boolean | (required) | | options.SMS.daily | object | | | options.SMS.daily.enabled | boolean | (required) | | options.SMS.daily.hour | string | | | options.SMS.weekly | object | | | options.SMS.weekly.enabled | boolean | (required) | | options.SMS.weekly.hour | string | | | options.SMS.weekly.day | string | | | options.SMS.monthly | object | | | options.SMS.monthly.enabled | boolean | (required) | | options.SMS.monthly.hour | string | | | options.SMS.monthly.date | “first” | “last” | | | options.CALL | object | | | options.CALL.defaultDeliveryOption | “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” | (required) | | options.CALL.off | object | | | options.CALL.off.enabled | boolean | (required) | | options.CALL.instant | object | | | options.CALL.instant.enabled | boolean | (required) | | options.CALL.hourly | object | | | options.CALL.hourly.enabled | boolean | (required) | | options.CALL.daily | object | | | options.CALL.daily.enabled | boolean | (required) | | options.CALL.daily.hour | string | | | options.CALL.weekly | object | | | options.CALL.weekly.enabled | boolean | (required) | | options.CALL.weekly.hour | string | | | options.CALL.weekly.day | string | | | options.CALL.monthly | object | | | options.CALL.monthly.enabled | boolean | (required) | | options.CALL.monthly.hour | string | | | options.CALL.monthly.date | “first” | “last” | | | options.PUSH | object | | | options.PUSH.defaultDeliveryOption | “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” | (required) | | options.PUSH.off | object | | | options.PUSH.off.enabled | boolean | (required) | | options.PUSH.instant | object | | | options.PUSH.instant.enabled | boolean | (required) | | options.PUSH.hourly | object | | | options.PUSH.hourly.enabled | boolean | (required) | | options.PUSH.daily | object | | | options.PUSH.daily.enabled | boolean | (required) | | options.PUSH.daily.hour | string | | | options.PUSH.weekly | object | | | options.PUSH.weekly.enabled | boolean | (required) | | options.PUSH.weekly.hour | string | | | options.PUSH.weekly.day | string | | | options.PUSH.monthly | object | | | options.PUSH.monthly.enabled | boolean | (required) | | options.PUSH.monthly.hour | string | | | options.PUSH.monthly.date | “first” | “last” | | | options.WEB_PUSH | object | | | options.WEB_PUSH.defaultDeliveryOption | “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” | (required) | | options.WEB_PUSH.off | object | | | options.WEB_PUSH.off.enabled | boolean | (required) | | options.WEB_PUSH.instant | object | | | options.WEB_PUSH.instant.enabled | boolean | (required) | | options.WEB_PUSH.hourly | object | | | options.WEB_PUSH.hourly.enabled | boolean | (required) | | options.WEB_PUSH.daily | object | | | options.WEB_PUSH.daily.enabled | boolean | (required) | | options.WEB_PUSH.daily.hour | string | | | options.WEB_PUSH.weekly | object | | | options.WEB_PUSH.weekly.enabled | boolean | (required) | | options.WEB_PUSH.weekly.hour | string | | | options.WEB_PUSH.weekly.day | string | | | options.WEB_PUSH.monthly | object | | | options.WEB_PUSH.monthly.enabled | boolean | (required) | | options.WEB_PUSH.monthly.hour | string | | | options.WEB_PUSH.monthly.date | “first” | “last” | | | options.SLACK | object | | | options.SLACK.defaultDeliveryOption | “off” | “instant” | “hourly” | “daily” | “weekly” | “monthly” | (required) | | options.SLACK.off | object | | | options.SLACK.off.enabled | boolean | (required) | | options.SLACK.instant | object | | | options.SLACK.instant.enabled | boolean | (required) | | options.SLACK.hourly | object | | | options.SLACK.hourly.enabled | boolean | (required) | | options.SLACK.daily | object | | | options.SLACK.daily.enabled | boolean | (required) | | options.SLACK.daily.hour | string | | | options.SLACK.weekly | object | | | options.SLACK.weekly.enabled | boolean | (required) | | options.SLACK.weekly.hour | string | | | options.SLACK.weekly.day | string | | | options.SLACK.monthly | object | | | options.SLACK.monthly.enabled | boolean | (required) | | options.SLACK.monthly.hour | string | | | options.SLACK.monthly.date | “first” | “last” | |

User

getAccountMetadata()

Get account-level metadata including logo, VAPID key, and web push status

// No parameters
await pingram.user.getAccountMetadata();

Parameters

This endpoint does not need any parameter.

getAvailableSlackChannels()

Get list of Slack channels and users for the authenticated user

// Path parameter only
await pingram.user.getAvailableSlackChannels('userId_example');

Parameters

Name Type Description
userId string User ID

getInAppNotifications()

Get in-app notifications for a user

// No parameters
await pingram.user.getInAppNotifications();

Parameters

Name Type Description
before string Timestamp or ISO date to fetch notifications before
count number Number of notifications to return (default 10)

getInAppUnreadCount()

Get the count of unread in-app notifications for a user

// No parameters
await pingram.user.getInAppUnreadCount();

Parameters

This endpoint does not need any parameter.

getUser()

Get a user by ID. All users exist implicitly, returns basic user object if not found in DB.

// Path parameter only
await pingram.user.getUser('userId_example');

Parameters

Name Type Description
userId string User ID

identify()

Create or update a user with the given ID. Updates lastSeenTime automatically.

// Path parameter + request body
await pingram.user.identify('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | —————–– | ————— | ——————————— | — | | userId | string | User ID | | postUserRequest | PostUserRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
id string Unique user identifier. Required.
email string User’s email address for email notifications.
number string User’s phone number for SMS/call notifications.
pushTokens object[] Mobile push tokens (FCM, APN) for push notifications.
pushTokens[].type “FCM” | “APN” (required)
pushTokens[].token string (required)
pushTokens[].device object (required)
pushTokens[].device.app_id string
pushTokens[].device.ad_id string
pushTokens[].device.device_id string (required)
pushTokens[].device.platform string
pushTokens[].device.manufacturer string
pushTokens[].device.model string
pushTokens[].environment string used by APN to differentiate between sandbox and production builds (sandbox/undefined or production)
webPushTokens object[] Web push subscription config from the browser.
webPushTokens[].sub object (required) Configuration for a Push Subscription. This can be obtained on the frontend by calling serviceWorkerRegistration.pushManager.subscribe(). The expected format is the same output as JSON.stringify’ing a PushSubscription in the browser.
webPushTokens[].sub.endpoint string (required)
webPushTokens[].sub.keys object (required)
webPushTokens[].sub.keys.p256dh string (required)
webPushTokens[].sub.keys.auth string (required)
timezone string User’s timezone (e.g. “America/New_York”) for scheduling.
slackChannel string The destination channel of slack notifications sent to this user. Can be either of the following: - Channel name, e.g. “test” - Channel name with # prefix, e.g. “#test” - Channel ID, e.g. “C1234567890” - User ID for DM, e.g. “U1234567890” - Username with @ prefix, e.g. “@test”
slackToken object
slackToken.access_token string
slackToken.app_id string
slackToken.authed_user object
slackToken.authed_user.access_token string
slackToken.authed_user.expires_in number
slackToken.authed_user.id string
slackToken.authed_user.refresh_token string
slackToken.authed_user.scope string
slackToken.authed_user.token_type string
slackToken.bot_user_id string
slackToken.enterprise object
slackToken.enterprise.id string
slackToken.enterprise.name string
slackToken.error string
slackToken.expires_in number
slackToken.incoming_webhook object
slackToken.incoming_webhook.channel string
slackToken.incoming_webhook.channel_id string
slackToken.incoming_webhook.configuration_url string
slackToken.incoming_webhook.url string
slackToken.is_enterprise_install boolean
slackToken.needed string
slackToken.ok boolean (required)
slackToken.provided string
slackToken.refresh_token string
slackToken.scope string
slackToken.team object
slackToken.team.id string
slackToken.team.name string
slackToken.token_type string
slackToken.warning string
slackToken.response_metadata object
slackToken.response_metadata.warnings string[]
slackToken.response_metadata.next_cursor string
slackToken.response_metadata.scopes string[]
slackToken.response_metadata.acceptedScopes string[]
slackToken.response_metadata.retryAfter number
slackToken.response_metadata.messages string[]

markInAppNotificationsAsSeen()

Mark in-app web notifications as seen/read for a user

// Request body only
await pingram.user.markInAppNotificationsAsSeen({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ————————————— | ———————————– | ——————————— | — | | inAppNotificationUnreadClearRequest | InAppNotificationUnreadClearRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
notificationId string
trackingId string

updateInAppNotificationStatus()

Update in-app web notification status (opened, archived, clicked, etc.)

// Request body only
await pingram.user.updateInAppNotificationStatus({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});

Parameters

| Name | Type | Description | | ——————————— | —————————– | ——————————— | — | | inAppNotificationPatchRequest | InAppNotificationPatchRequest | See Request Body Properties below | |

Request Body Properties

Name Type Description
trackingIds string[] (required)
opened string
clicked string
archived string
actioned1 string
actioned2 string
reply object
reply.date string (required)
reply.message string (required)
replies object[]
replies[].date string (required)
replies[].message string (required)

Users

deleteUser()

Delete a user and all associated data (in-app notifications, preferences, and user record)

// Path parameter only
await pingram.users.deleteUser('userId_example');

Parameters

Name Type Description
userId string User ID
envId string Environment ID (required when using JWT auth)

listUsers()

Get all users for an environment with pagination support

// No parameters
await pingram.users.listUsers();

Parameters

Name Type Description
limit number Maximum number of users to return (default
nextToken string Pagination token for next page
envId string Environment ID (required when using JWT auth)

removeUserFromSuppression()

Remove user suppression status for a specific channel

// Path parameter only
await pingram.users.removeUserFromSuppression('userId_example');

Parameters

Name Type Description
userId string User ID
channel string Channel type (EMAIL)
envId string Environment ID (required when using JWT auth)