Pingram Send SMS

A GitHub Action to send an SMS from your workflows with Pingram — page on-call when a deploy fails, or notify by text message on any workflow event.

- uses: pingram-io/github-actions-send-sms@v1
  with:
    api-key: ${{ secrets.PINGRAM_API_KEY }}
    type: oncall-page
    to: '+15551234567'
    message: 'Production deploy failed: ${{ github.repository }}'

Quote phone numbers in YAML. Unquoted, +1555... is ambiguous and some parsers will mangle it.

Need email instead? See Pingram Send Email.

Setup

1. Grab a pingram_sk_... key from the API Keys page in the Pingram dashboard.
2. Add it as a repository secret named PINGRAM_API_KEY.

Examples

Page on-call when a deploy fails

if: failure() is what makes this a failure notification — the step only runs when something earlier in the job failed.

- uses: pingram-io/github-actions-send-sms@v1
  if: failure()
  with:
    api-key: ${{ secrets.PINGRAM_API_KEY }}
    type: oncall-page
    to: '+15551234567'
    message: |
      ${{ github.workflow }} failed on ${{ github.ref_name }}
      ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

Page several people

to takes a comma-separated list. Each number is sent its own SMS.

- uses: pingram-io/github-actions-send-sms@v1
  if: failure()
  with:
    api-key: ${{ secrets.PINGRAM_API_KEY }}
    type: oncall-page
    to: '+15551234567, +15559876543'
    message: 'Production deploy failed: ${{ github.repository }}'

Send an MMS

- uses: pingram-io/github-actions-send-sms@v1
  with:
    api-key: ${{ secrets.PINGRAM_API_KEY }}
    type: build-artifacts
    to: '+15551234567'
    message: Coverage report
    media-urls: https://example.com/coverage.png

Capture the tracking id

- uses: pingram-io/github-actions-send-sms@v1
  id: notify
  with:
    api-key: ${{ secrets.PINGRAM_API_KEY }}
    type: oncall-page
    to: '+15551234567'
    message: Deployed

- run: |
    echo "Sent as ${{ steps.notify.outputs.tracking-id }}"

Inputs

Name	Required	Default	Description
api-key	yes		Pingram API key (pingram_sk_...)
type	yes		Label used to group the send in your logs
to	yes		E.164 phone number, or a comma-separated list
message	see note		Message body
from	no		Sender number override (E.164)
media-urls	no		Comma-separated media URLs for MMS
schedule	no		ISO 8601 timestamp to send at instead of now
region	no	us	us, eu or ca
base-url	no		Custom API base URL, overrides region
fail-on-error	no	true	Fail the step when the send fails

message is required unless you set media-urls, which sends a media-only MMS.

type is any string you choose. It does not have to exist in the dashboard beforehand — it is what the send is grouped under in Logs and Insights.

Set fail-on-error: false to log a warning instead of failing the job, so a notification problem can never block a deploy.

Outputs

Name	Description
tracking-id	Tracking id(s) for the send — comma-separated when to has multiple recipients

Regions

Use the region your Pingram account lives in. us is the default.

Region	API
us	api.pingram.io
eu	api.eu.pingram.io
ca	api.ca.pingram.io

Pinning

@v1 tracks the latest v1.x release. To pin exactly, use a commit SHA:

- uses: pingram-io/github-actions-send-sms@<commit-sha>

Support

Questions, bugs or a missing input? Email [email protected].

License

MIT