Pingram CLI

Official command-line interface for the Pingram API.

Install

Requires Node.js 18+.

npm install -g pingram-cli

curl -fsSL https://raw.githubusercontent.com/pingram-io/cli/main/install.sh | bash

brew install pingram-io/cli/pingram

irm https://raw.githubusercontent.com/pingram-io/cli/main/install.ps1 | iex

Authentication

Get your API key from the API Keys page. Your account region (us, eu, or ca) is shown on the API Keys page — use it when logging in.

pingram login

Accounts

accounts create

Create an additional account for the authenticated user

pingram accounts create \
  --name value

Options:

--name (required) — name
--plan (JSON) — Billing to copy onto a new additional account.
--member-emails (repeatable) — 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.

accounts list

List accounts the authenticated user can access

pingram accounts list

Broadcasts

broadcasts 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.

pingram broadcasts cancel

Arguments:

<broadcastId> — Broadcast ID

broadcasts 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.

pingram broadcasts create \
  --name value \
  --audience '{"filter":"value","emails":"value"}' \
  --from-name value \
  --from-address value \
  --subject value \
  --html value

Options:

--name (required) — name
--type — Notification type id. Optional on create; required before send/schedule. Created on the fly when missing.
--channel — channel. Allowed values: email.
--audience (required) (JSON) — Broadcast audience: exactly one of filter (Mongo-style query evaluated against synced user objects) or emails (raw list, max 10,000 addresses; for larger audiences use filter after syncing users via the Users API).
--from-name (required) — from Name
--from-address (required) — from Address
--reply-to-address — reply To Address
--subject (required) — subject
--html (required) — html
--internal-template — Optional visual-editor source. Can only be set at create time and must stay paired with html.

broadcasts delete

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

pingram broadcasts delete

Arguments:

<broadcastId> — Broadcast ID

broadcasts get

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

pingram broadcasts get

Arguments:

<broadcastId> — Broadcast ID

broadcasts list

List email broadcasts for the account, newest first. Returns metadata without html or internalTemplate bodies. A live-filter audience includes the filter. A raw email audience includes emailCount and omits the addresses. Paginate with limit (default 50, max 100) and nextToken.

pingram broadcasts list

Query options:

--limit — Max broadcasts to return (default 50)
--next-token — Pagination token

broadcasts metrics

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

pingram broadcasts metrics

Arguments:

<broadcastId> — Broadcast ID

broadcasts pause

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

pingram broadcasts pause

Arguments:

<broadcastId> — Broadcast ID

broadcasts recipients

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.

pingram broadcasts recipients

Arguments:

<broadcastId> — Broadcast ID

Query options:

--status — Filter
--limit — Max recipients to return (default 50)
--next-token — Pagination token

broadcasts resume

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

pingram broadcasts resume

Arguments:

<broadcastId> — Broadcast ID

broadcasts 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.

pingram broadcasts schedule value

Arguments:

<broadcastId> — Broadcast ID
<sendAt> — ISO datetime in the future.

broadcasts 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.

pingram broadcasts send

Arguments:

<broadcastId> — Broadcast ID

broadcasts 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.

pingram broadcasts update

Arguments:

<broadcastId> — Broadcast ID

Options:

--name — name
--type — type
--channel — channel. Allowed values: email.
--audience (JSON) — Broadcast audience: exactly one of filter (Mongo-style query evaluated against synced user objects) or emails (raw list, max 10,000 addresses; for larger audiences use filter after syncing users via the Users API).
--from-name — from Name
--from-address — from Address
--reply-to-address — Omit to leave unchanged. Empty string clears Reply-To.
--subject — subject
--html — html
--internal-template — Optional visual-editor source. Can be updated only when the broadcast was created with it; cannot be added to an html-only broadcast. Pair with html.

Domains

domains add

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

pingram domains add value

Arguments:

<sender> — sender

domains delete

Remove a sender domain from the account.

pingram domains delete

Arguments:

<sender> — Sender domain (URL encoded)

domains list

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

pingram domains list

domains start-verification

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

pingram domains start-verification

Arguments:

<sender> — Sender domain (URL encoded)

Email

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.

pingram email send \
  --type value \
  --to value \
  --subject value \
  --html value

Options:

--type (required) — The notification type to send.
--to (required) — The email address of the recipient.
--subject (required) — The subject of the email.
--html (required) — The HTML body of the email.
--from-name — The display name of the sender.
--from-address — The email address of the sender.
--preview-text — The preview text of the email.
--reply-to-addresses (repeatable) — The reply-to addresses of the email.
--cc-addresses (repeatable) — The CC addresses of the email.
--bcc-addresses (repeatable) — The BCC addresses of the email.
--open-tracking — When false, this send does not record opens and no open pixel is added. Delivery, bounce, and complaint events are unchanged. Defaults to true.
--click-tracking — When false, links are left as written and clicks are not recorded. Delivery, bounce, and complaint events are unchanged. Defaults to true.
--schedule — The ISO 8601 datetime to schedule the email.

Logs

logs get

Get logs by tracking IDs (comma-separated, max 25 IDs). Returns full log objects with personally identifiable information (recipients, user ids, phone numbers, and request details). For a simple delivery check, use Get Delivery Status.

pingram logs get

Arguments:

<trackingIds> — Comma-separated tracking IDs (URL encoded)

logs list

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

pingram logs list

Query options:

--limit — Maximum number of logs to return (default
--cursor — Pagination cursor for next page

logs query

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

pingram logs query

Options:

--date-range-filter (repeatable) — A tuple of [startTime, endTime] for the date range filter, each representing a unix timestamp.
--user-filter — user Filter
--env-id-filter (repeatable) — env Id Filter
--status-filter — status Filter
--channel-filter (repeatable) — channel Filter. Allowed values: email, inapp, sms, call, voice, web_push, mobile_push, slack.
--notification-filter (repeatable) — notification Filter

logs query-result

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

pingram logs query-result

Arguments:

<queryId> — Query ID returned by Start Log Query

logs retention

Get log retention period in days for the account

pingram logs retention

logs status

Look up email and SMS delivery status for up to 25 tracking IDs. Each entry is the tracking id, channel (EMAIL or SMS), status, and the time that status was recorded. The result does not include recipients, phone numbers, user ids, request bodies, IP addresses, account ids, or user-agent data. Unknown tracking ids are omitted. Other channels are not included.

pingram logs status

Arguments:

<trackingIds> — Comma-separated tracking IDs (URL encoded, max 25)

logs tail

Get last 100 logs from the stream

pingram logs tail

Members

members list

Get a list of team members in the account

pingram members list

members remove

Remove a member from the account

pingram members remove

Arguments:

<userId> — User ID or email address (URL encoded)

Numbers

numbers list

List active phone numbers registered for the account, including voice agent binding state.

pingram numbers list

numbers list-released

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.

pingram numbers list-released

numbers order

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

pingram numbers order value

Arguments:

<phoneNumber> — E.164 from search results

numbers release

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

pingram numbers release

Arguments:

<phoneNumber> — E.164 phone number to release

numbers search

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

pingram numbers search

Query options:

--country-code (required) — ISO 3166-1 alpha-2 country code (e.g., US, CA)
--features — Comma-separated
--area-code — National destination / area code filter
--limit — Max results (default 10, max 50)

Sms

sms send

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

pingram sms send \
  --type value \
  --to value

Options:

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

Usage

usage get

Get usage for the authenticated account.

pingram usage get

usage history

Get historical usage for the authenticated account over a date range, summed by UTC calendar month or billing cycle from daily counts.

pingram usage history

Query options:

--start-date (required) — Start date (YYYY-MM-DD) for the range
--end-date (required) — End date (YYYY-MM-DD) for the range
--group-by — calendar (UTC months, default) or billing (account billing cycles)

Webhooks

webhooks create

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.

pingram webhooks create \
  --webhook value \
  --events EMAIL_OPEN

Options:

--webhook (required) — Public HTTPS URL that accepts POST with a JSON event body. Return 2xx to acknowledge. Private, loopback, and link-local addresses are rejected. Requests include X-Pingram-Id, X-Pingram-Signature (v1 HMAC-SHA256), and X-Pingram-Timestamp.
--events (required) (repeatable) — Full set of event types to deliver to this URL. Omitting an event on update unsubscribes it. Inbound SMS to the free shared number only works when that person has already received a text from this number. Inbound SMS to a dedicated number works normally. Allowed values: 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, ACCOUNT_USAGE.

webhooks delete

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.

pingram webhooks delete

Arguments:

<endpointId> — Id of the webhook endpoint, from list or create.

webhooks list

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

pingram webhooks list

webhooks update

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.

pingram webhooks update \
  --webhook value \
  --events EMAIL_OPEN

Arguments:

<endpointId> — Id of the webhook endpoint, from list or create.

Options:

--webhook (required) — Public HTTPS URL that accepts POST with a JSON event body. Return 2xx to acknowledge. Private, loopback, and link-local addresses are rejected. Requests include X-Pingram-Id, X-Pingram-Signature (v1 HMAC-SHA256), and X-Pingram-Timestamp.
--events (required) (repeatable) — Full set of event types to deliver to this URL. Omitting an event on update unsubscribes it. Inbound SMS to the free shared number only works when that person has already received a text from this number. Inbound SMS to a dedicated number works normally. Allowed values: 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, ACCOUNT_USAGE.