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.
(required) Account whose saved payment method is copied onto the new account. The caller must be an owner of this account.
memberEmails
string[]
Emails to add or invite to the new account. Existing members of any account the caller belongs to are added directly; everyone else is invited.
listAccounts()
List accounts the authenticated user can access
// No parameters
await pingram.accounts.listAccounts();
Parameters
This endpoint does not need any parameter.
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.
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
List active phone numbers registered for the account, including voice agent binding state.
// 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.
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.
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.
// 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):
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.
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.)