Source: https://cli.nylas.com/guides/vip-sender-email-alerts-cli

# Get Alerts for VIP Sender Emails

Fire an alert the instant a VIP emails you. This guide wires a message.created webhook that checks each new sender against an allowlist, then notifies you — plus a cron fallback using nylas email search for environments that can't host an HTTPS endpoint.

Written by [Caleb Geene](https://cli.nylas.com/authors/caleb-geene) Director, Site Reliability Engineering

Reviewed by [Qasim Muhammad](https://cli.nylas.com/authors/qasim-muhammad)

Updated June 9, 2026

> **TL;DR:** Register a `message.created` webhook, match the sender against an allowlist, and notify in real time. No public endpoint? Poll with `nylas email search "*" --from` on a cron. One of these two delivers alerts in under a second — the comparison section says which, and what the trade-off costs.

## How do I get a real-time alert when a VIP emails me?

A VIP sender alert fires a notification the moment a message arrives from someone on your priority list. The push approach registers a `message.created` webhook with Nylas CLI: every new inbound email POSTs to your endpoint, your handler reads the sender, and if it matches the allowlist you alert. Latency is typically under one second from receipt to notification.

The `nylas webhook create` command points one HTTPS URL at the `message.created` trigger in a single call. Run `nylas webhook triggers` first to confirm the trigger name. Each delivery is a POST carrying the message ID, the `from` address, subject, and a Unix timestamp, so your handler has everything it needs without a follow-up fetch.

```bash
nylas webhook create \
  --url https://your-server.example.com/vip-alerts \
  --triggers message.created \
  --description "vip sender alerts"
```

## How do I match a new email against a VIP allowlist?

A VIP allowlist is a flat list of the email addresses and domains whose messages should alert you. Your webhook handler reads the sender from each `message.created` payload, normalizes it to lowercase, and checks membership. A 12-name list fits in a few lines and matches in well under a millisecond per event.

The sender address lives in the `from` array of every Nylas message object, where each entry has `name` and `email` fields. RFC 5322 §3.6.2 defines that “From” field, and a single message can list more than one author, so iterate the array rather than assuming one sender. Match on the full address for individuals and on the domain suffix for whole companies.

```bash
# vip.txt holds one address or @domain per line
cat > vip.txt <<'EOF'
ceo@acme.com
@bigcustomer.com
investor@fund.vc
EOF

# Inside your webhook handler: extract sender, test membership
sender=$(jq -r '.data.object.from[0].email' event.json | tr 'A-Z' 'a-z')
domain="@${sender#*@}"
if grep -qixF -e "$sender" -e "$domain" vip.txt; then
  echo "VIP MATCH: $sender"
fi
```

## How do I send the notification once a VIP matches?

Once the sender matches the allowlist, the alert itself is just another channel write. The simplest path keeps everything inside the CLI: call `nylas email send` to forward a heads-up to your phone's SMS gateway or a secondary address. A single send replaces SMTP setup, TLS certificates, and DNS MX records, and delivers across Gmail and Outlook with the same command.

The `--metadata` flag tags the alert with searchable key-value pairs, so you can later list every VIP notification with one query. Nylas indexes keys `key1` through `key5` as filterable, allowing up to 50 pairs per message, set at send time. To route alerts to Slack instead of email, the Slack notifications guide below covers the incoming-webhook pattern.

```bash
nylas email send \
  --to 15551234567@vtext.com \
  --subject "VIP email: $sender" \
  --body "New message from $sender just landed in your inbox." \
  --metadata kind=vip-alert --metadata key1=vip \
  --yes
```

## How do I poll for VIP emails without a public endpoint?

When you can't host an HTTPS endpoint — a laptop behind NAT, a locked-down CI runner, a headless box — poll instead of pushing. The `nylas email search` command filters by sender server-side with `--from`, so a cron job that runs every five minutes asks the provider only for VIP mail and skips everything else.

A five-minute interval means worst-case alert latency of 300 seconds versus the webhook's sub-second push, but it needs zero inbound network access. The `--unread` flag narrows the result to messages you haven't opened, and `--json` gives machine-readable output for the loop. The crontab(5) format takes five time fields, so `*/5 * * * *` schedules a check every fifth minute.

```bash
#!/usr/bin/env bash
# vip-poll.sh — run from cron: */5 * * * * /path/vip-poll.sh
while read -r vip; do
  hits=$(nylas email search "*" --from "$vip" --unread --json | jq length)
  if [ "$hits" -gt 0 ]; then
    nylas email send --to you@example.com \
      --subject "VIP: $hits new from $vip" \
      --body "Check your inbox." --yes
  fi
done < vip.txt
```

## Why prefer a webhook over polling for VIP alerts?

A webhook beats polling on latency and API cost for VIP alerts. The push model delivers in under one second and makes zero idle requests; a cron poll every five minutes adds up to 288 requests per address per day, most of them returning nothing. Polling wins only when you genuinely can't accept an inbound HTTPS connection.

Provider behavior shapes the choice too. Gmail's push notifications are documented to deliver within seconds of a change, and Microsoft Graph subscriptions POST a change notification to your endpoint on the same model. Verify each delivery before trusting it: the `nylas webhook verify` command checks the HMAC-SHA256 signature against your signing secret, and an unauthenticated endpoint will accept forged VIP events from anyone who finds the URL. Reject any payload whose signature doesn't match with a 401 before parsing the body.

```bash
# Confirm a captured payload + signature against your webhook secret
nylas webhook verify \
  --payload-file event.json \
  --signature "$X_NYLAS_SIGNATURE" \
  --secret "$WEBHOOK_SECRET"
```

Test the whole loop locally before deploying. The `nylas webhook server` command starts a receiver that prints each event, so you can email yourself from a VIP address and watch the match fire end to end.

## Next steps

- [Send and Parse Email with One API](https://cli.nylas.com/guides/send-and-parse-email-one-api) — Send with nylas email send and parse replies with nylas email…
- [Send Email Alerts to Microsoft Teams](https://cli.nylas.com/guides/email-to-teams-notifications) — Forward matching email into a Teams channel after the connector…
- [Create Zendesk Tickets from Email (CLI)](https://cli.nylas.com/guides/email-to-zendesk-tickets) — Pull inbound email as JSON with the CLI, map subject and sender to…
- [Auto-Organize Incoming Email by Rule](https://cli.nylas.com/guides/auto-label-incoming-email-cli) — Auto label incoming email from the terminal.
- [Send Yourself Follow-Up Reminders](https://cli.nylas.com/guides/follow-up-reminder-email-cli) — Find sent threads with no reply via nylas email threads and…
- [Track email opens, clicks, and replies](https://cli.nylas.com/guides/track-email-opens-replies-cli) — the same webhook triggers, applied to engagement signals
- [Send email notifications to Slack](https://cli.nylas.com/guides/email-to-slack-notifications) — route VIP alerts to a channel via an incoming webhook
- [Parse inbound email webhooks](https://cli.nylas.com/guides/parse-inbound-email-webhooks) — extract sender, subject, and body from each payload
- [Turn emails into GitHub issues](https://cli.nylas.com/guides/email-to-github-issues) — another message.created handler, with a different action
- [Command reference](https://cli.nylas.com/docs/commands) — every flag, subcommand, and example
- [RFC 5322 §3.6.2](https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.2) — the “From” field a message can carry more than one of
- [Gmail API push notifications](https://developers.google.com/workspace/gmail/api/guides/push) — how Gmail delivers near-real-time change events
- [Microsoft Graph: create subscription](https://learn.microsoft.com/en-us/graph/api/subscription-post-subscriptions) — subscribe to Outlook message change notifications