Pingram CLI

Official command-line interface for the Pingram API.

Install

npm install -g pingram-cli

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

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

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.
• --schedule — The ISO 8601 datetime to schedule the email.

Logs

logs get

Get logs by tracking IDs (comma-separated, max 25 IDs). Use after sending email or SMS to look up 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, 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 tail

Get last 100 logs from the stream

pingram logs tail

Members

members list

Get a list of team members in the organization

pingram members list

members remove

Remove a member from the organization

pingram members remove

Arguments:

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

Numbers

numbers list

List active phone numbers registered for the account.

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’s organization (new billing model).

pingram usage get

usage history

Get historical usage for the authenticated account’s organization over a date range.

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

Webhooks

webhooks delete

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

pingram webhooks delete

webhooks get

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

pingram webhooks get

webhooks update

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

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

Options:

• --webhook (required) — Destination URL that receives webhook event payloads. Must be a valid http(s) URL.
• --events (required) (repeatable) — List of event types that should be forwarded to the webhook URL. 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, VOICE_INBOUND.