Node.js SDK

Setup & Initialization

Install using one of the following package managers:

npm install pingram

yarn add pingram

pnpm add pingram

Import:

import { Pingram } from 'pingram';

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'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'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) |

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

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

getTemplate()

Get a single template by ID

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

Parameters

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'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'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) |