Node.js SDK

Setup & Initialization

1. Install using one of the following package managers:

npm install pingram

yarn add pingram

pnpm add pingram

2. Import:

import { Pingram } from 'pingram';

3. Initialize:

const pingram = new Pingram({
  apiKey: 'pingram_sk_...' // Your API key from the dashboard
});

• 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

Request Body Properties

Webhooks

createWebhook()

Create a webhook endpoint. Pingram POSTs signed JSON to the URL when one of the subscribed events happens. The response includes id and a signing secret starting with pingram_whsecret_. Save it and verify the X-Pingram-Signature header. Updates keep this secret. At most 10 endpoints per account. The URL must be a public HTTPS URL and should return 2xx.

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

Parameters

Request Body Properties

deleteWebhook()

Delete one webhook endpoint by id from list or create. That URL stops receiving its events. Other endpoints on the account are left as they are.

// Path parameter only
await pingram.webhooks.deleteWebhook('endpointId_example');

Parameters

listWebhooks()

List webhook endpoints on the current account, including each id, URL, subscribed events, and signing secret. Use the id with update or delete.

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

Parameters

This endpoint does not need any parameter.

updateWebhook()

Replace one webhook endpoint's URL and its full event subscription. endpointId comes from list or create. The signing secret stays the same. events is the complete set; omitting an event unsubscribes it. The URL must be a public HTTPS URL.

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

Parameters

Request Body Properties

Accounts

createAccount()

Create an additional account for the authenticated user

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

Parameters

Request Body Properties

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

Request Body Properties

deleteAddress()

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

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

Parameters

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

Request Body Properties

Broadcasts

_delete()

Delete an email broadcast. Allowed for drafts, scheduled, paused, completed, and canceled broadcasts. Not allowed while status is sending.

// Path parameter only
await pingram.broadcasts._delete('broadcastId_example');

Parameters

archive()

Archive an email broadcast so it is hidden from the default broadcast list. Allowed for draft, paused, sent, and canceled broadcasts. Not allowed while sending or scheduled.

// Path parameter only
await pingram.broadcasts.archive('broadcastId_example');

Parameters

cancel()

Cancel an email broadcast. Scheduled broadcasts revert to draft and drop their schedule. Sending or paused broadcasts become canceled; remaining pending recipients are skipped.

// Path parameter only
await pingram.broadcasts.cancel('broadcastId_example');

Parameters

create()

Create a draft email broadcast. html is the send-ready body. Optional internalTemplate is visual-editor source; if set it must be paired with html and cannot be added later. Set audience to either a Mongo-style user filter (sync users via Users API first; for large lists) or a raw email list (max 10,000). Include name, from fields, subject, and HTML. Notification type is optional on create and required before send or schedule; it is created automatically if missing.

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

Parameters

Request Body Properties

get()

Get one email broadcast by ID, including the send-ready html body, optional internalTemplate (visual-editor source), and audience definition.

// Path parameter only
await pingram.broadcasts.get('broadcastId_example');

Parameters

getMetrics()

Poll live email broadcast metrics: status, optional pausedReason or scheduleAt, and aggregate counters (total, sent, delivered, opened, clicked, bounced, complained, unsubscribed, skipped, failed).

// Path parameter only
await pingram.broadcasts.getMetrics('broadcastId_example');

Parameters

list()

List email broadcasts for the account, newest first. Returns metadata and counters without html or internalTemplate bodies. Paginate with limit (default 50, max 100) and nextToken.

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

Parameters

listRecipients()

List email broadcast recipients with per-recipient delivery fact timestamps (sentAt, deliveredAt, openedAt, etc.). Derive display status client-side from timestamps. Filter by status (pending, sent, delivered, opened, clicked, bounced, complained, unsubscribed, skipped, failed, problems). Paginate with limit (default 50, max 200) and nextToken.

// Path parameter only
await pingram.broadcasts.listRecipients('broadcastId_example');

Parameters

pause()

Pause an actively sending email broadcast. Status becomes paused with pausedReason PAUSED_BY_USER.

// Path parameter only
await pingram.broadcasts.pause('broadcastId_example');

Parameters

resume()

Resume a paused email broadcast. Continues sending remaining recipients. Broadcasts paused for spam content cannot be resumed.

// Path parameter only
await pingram.broadcasts.resume('broadcastId_example');

Parameters

schedule()

Schedule a draft email broadcast for a future ISO datetime (sendAt). Requires a non-empty subject. fromAddress must be the platform default sender or a domain verified for this account (Settings → Domain Verification). The platform default sender is for testing only (at most 10 recipients, heavily throttled). Cancels any existing schedule when the broadcast is returned to draft via cancel.

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

Parameters

Request Body Properties

send()

Send a draft email broadcast immediately. Requires a non-empty subject. fromAddress must be the platform default sender or a domain verified for this account (Settings → Domain Verification). The platform default sender is for testing only (at most 10 recipients, heavily throttled). Transitions status to sending and starts delivery.

// Path parameter only
await pingram.broadcasts.send('broadcastId_example');

Parameters

unarchive()

Restore an archived email broadcast to the default broadcast list.

// Path parameter only
await pingram.broadcasts.unarchive('broadcastId_example');

Parameters

update()

Update a draft email broadcast (name, type, audience, sender, subject, html). html is the send-ready body. Send an empty replyToAddress to clear Reply-To. internalTemplate can be updated only when the broadcast was created with it; it cannot be added to an html-only broadcast or removed. Only drafts can be edited; scheduled or active broadcasts are locked.

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

Parameters

Request Body Properties

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

Request Body Properties

deleteDomain()

Remove a sender domain from the account.

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

Parameters

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

Email

deleteSuppressions()

Start removing all email suppressions of the given reason (`retryable` or `bounces`) for users in the environment. Returns immediately after the job is queued — suppressions are not yet cleared when this response is received. Large removals are processed in the background in batches.

// Path parameter only
await pingram.email.deleteSuppressions('reason_example');

Parameters

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

Request Body Properties

Environments

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

Request Body Properties

Library

create()

Create an upload slot in the account library. contentType must be image/png, image/jpeg, image/gif, or image/webp. PUT the file to the returned uploadUrl with that Content-Type, then use the returned url in emails and the editor.

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

Parameters

Request Body Properties

list()

List files in the account library for a use-case, newest first. Paginate with limit (default 50, max 100) and nextToken.

// Path parameter only
await pingram.library.list('useCase_example');

Parameters

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

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

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

retryInbound()

Resend the EMAIL_INBOUND webhook for one inbound email. Uses the original tracking ID and does not count another email. Refused when the message is older than 30 days.

// Path parameter only
await pingram.logs.retryInbound('trackingId_example');

Parameters

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

Request Body Properties

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, 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

Request Body Properties

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

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

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

Request Body Properties

deleteAccount()

Permanently delete the authenticated user'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

Request Body Properties

disableMfa()

Disable MFA for the authenticated user

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

Parameters

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

Request Body Properties

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

Request Body Properties

Registrations

createUs10dlcBrand()

Create a new 10DLC brand registration. Sets brandStatus to pending_review; Pingram handles carrier submission after review.

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

Parameters

Request Body Properties

getUs10dlcBrand()

Get the 10DLC brand registration for the authenticated account. Returns null when no registration exists yet.

// No parameters
await pingram.registrations.getUs10dlcBrand();

Parameters

This endpoint does not need any parameter.

getUs10dlcCampaign()

Get the 10DLC campaign registration for the authenticated account. Returns null when no brand registration exists yet.

// No parameters
await pingram.registrations.getUs10dlcCampaign();

Parameters

This endpoint does not need any parameter.

updateUs10dlcBrand()

Update an existing 10DLC brand registration. Business fields are editable before carrier submission; workflow status is managed by Pingram.

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

Parameters

Request Body Properties

updateUs10dlcCampaign()

Update an existing 10DLC campaign registration. Campaign fields are editable before carrier submission; workflow status is managed by Pingram.

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

Parameters

Request Body Properties

Sender

deleteSchedule()

Delete (unschedule) an already scheduled notification

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

Parameters

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

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

Request Body Properties

SubNotifications

deleteSubNotification()

This endpoint is no longer maintained and should not be used.

// Path parameter only
await pingram.subNotifications.deleteSubNotification('notificationId_example');

Parameters

putSubNotification()

This endpoint is no longer maintained and should not be used.

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

Parameters

Request Body Properties

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

Request Body Properties

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

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

Request Body Properties

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

Request Body Properties

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

Request Body Properties

deleteNotificationType()

Delete a notification

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

Parameters

getNotificationType()

Get a specific notification by ID

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

Parameters

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

Request Body Properties

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.

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

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

Request Body Properties