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 one additional Pingram account (a separate workspace) for the signed-in user. The caller must already belong to an account. Requires a user session or personal access token; an account API key cannot call this. Does not create a login, and does not change, delete, or grant access to existing accounts. Omit plan and nothing is charged. The new account is ready for billing to be added later, and it cannot send until then. Setting plan charges immediately. It starts a paid subscription on the payment method already saved on sourceBillingAccountId, an account the caller must own. Optional memberEmails adds people who already share an account with the caller and invites everyone else.

Terminal window
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

Terminal window
pingram accounts list

Broadcasts

broadcasts cancel

Cancel an email broadcast. Scheduled broadcasts revert to draft and drop their schedule (they can be scheduled again). Sending or paused broadcasts become canceled; recipients already processed stay as they are, and remaining pending recipients are skipped and will not be sent. That skip cannot be undone.

Terminal window
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. A later update can add it to a draft by sending it with html. 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.

Terminal window
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. Pair with html. A later update can add it to a draft by sending it with html.

broadcasts delete

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

Terminal window
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.

Terminal window
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.

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

Terminal window
pingram broadcasts metrics

Arguments:

  • <broadcastId> — Broadcast ID

broadcasts pause

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

Terminal window
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.

Terminal window
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.

Terminal window
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.

Terminal window
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.

Terminal window
pingram broadcasts send

Arguments:

  • <broadcastId> — Broadcast ID

broadcasts update

Update a draft email broadcast. Fields you send replace the stored values (name, type, audience, sender, subject, html) and the previous values are not kept; omitted fields stay. html is the send-ready body. Send an empty replyToAddress to clear Reply-To. internalTemplate is visual-editor source: send it with html to add it to an html-only draft or to update it. It cannot be removed. Only drafts can be edited; scheduled or active broadcasts are locked. This does not send the broadcast.

Terminal window
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 — Visual-editor source. Send with html to add it to an html-only draft or to update it. Cannot be removed.

Domains

domains add

Start verification for a domain you already own so Pingram can use it for email. Pass a bare domain (example.com) or subdomain (mail.example.com). This does not purchase, transfer, renew, or control the domain, does not edit DNS, and does not disable sending or receiving on other platforms. It saves the domain on this Pingram account and returns DNS records for you to publish. Required DKIM lets Pingram send email from addresses on this domain once verification completes. Optional inbound MX, once you publish it, routes that domain’s inbound email to Pingram. This call only begins verification. Publish the records, then start verification in the dashboard or with the start-verification API. Adding a domain that is already on the account returns the existing records.

Terminal window
pingram domains add value

Arguments:

  • <sender> — sender

domains delete

Remove a sender domain from the account.

Terminal window
pingram domains delete

Arguments:

  • <sender> — Sender domain (URL encoded)

domains list

List domains already added to this Pingram account for email. Each entry includes verification status and the DNS records Pingram expects you to publish. Does not search a registrar, purchase or transfer a domain, change DNS, or include domains that have not been added to this account.

Terminal window
pingram domains list

domains start-verification

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

Terminal window
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.

Terminal window
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.

Terminal window
pingram logs get

Arguments:

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

logs list

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

Terminal window
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.

Terminal window
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.

Terminal window
pingram logs query-result

Arguments:

  • <queryId> — Query ID returned by Start Log Query

logs retention

Get log retention period in days for the account

Terminal window
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.

Terminal window
pingram logs status

Arguments:

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

logs tail

Get last 100 logs from the stream

Terminal window
pingram logs tail

Members

members list

Get a list of team members in the account

Terminal window
pingram members list

members remove

Remove a member from the account

Terminal window
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.

Terminal window
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.

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

Terminal window
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.

Terminal window
pingram numbers release

Arguments:

  • <phoneNumber> — E.164 phone number to release

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

Terminal window
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.

Terminal window
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.

Terminal window
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.

Terminal window
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 on a server outside Pingram. Pingram later POSTs signed JSON to that URL when one of the subscribed events happens. This call only saves the endpoint; it does not send a webhook and does not modify the destination server. 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.

Terminal window
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, VOICE_INBOUND, VOICE_CONNECTED, VOICE_ENDED, 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.

Terminal window
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.

Terminal window
pingram webhooks list

webhooks update

Replace one webhook endpoint’s URL and its full event subscription. The URL is a server outside Pingram. endpointId comes from list or create. The signing secret stays the same. events is the complete set; omitting an event unsubscribes it, and the previous URL stops receiving events. The previous URL and event list are not kept. The URL must be a public HTTPS URL.

Terminal window
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, VOICE_INBOUND, VOICE_CONNECTED, VOICE_ENDED, PUSH_FAILED, PUSH_UNSUBSCRIBE, CALL_FAILED, CALL_UNSUBSCRIBE, WEB_PUSH_FAILED, WEB_PUSH_UNSUBSCRIBE, SLACK_FAILED, SLACK_UNSUBSCRIBE, ACCOUNT_USAGE.