Skip to main content

FAQ

General​

What is Zyphr?​

Zyphr is a multi-channel notification platform that lets you send emails, push notifications, SMS, and in-app notifications through a single API. We handle deliverability, provider management, and tracking so you can focus on your product.

What channels does Zyphr support?​

  • Email — powered by AWS SES
  • Push Notifications — iOS (APNs), Android (FCM), Web Push
  • SMS — powered by Twilio
  • In-App Inbox — real-time with WebSocket support

Is there a free tier?​

Yes. The free tier includes 10 requests/second rate limit and a generous monthly message allowance. See Pricing for details.

Do you provide an SLA?​

Enterprise plans include an SLA with guaranteed uptime. Contact sales@zyphr.dev for details.

Authentication & API Keys​

How do I get an API key?​

  1. Log in to the Zyphr Dashboard
  2. Go to Settings > API Keys
  3. Click Create API Key
  4. Copy the key — it's only shown once

See Authentication for more details.

What's the difference between live and test keys?​

  • Live keys (zy_live_...) — Send real messages to real recipients
  • Test keys (zy_test_...) — Messages are simulated, no actual delivery

See Test Mode for details.

I'm getting "unauthorized" errors​

  • Verify your API key is correct and hasn't been revoked
  • Ensure you're using the X-API-Key header (not Authorization)
  • Check if your key has IP allowlist restrictions

Email​

My emails are going to spam​

  1. Verify your domain — This is required for production. See Domain Verification
  2. Check DKIM/SPF/DMARC — All three DNS records must be properly configured
  3. Use a dedicated sending domain — e.g., mail.yourapp.com rather than your root domain
  4. Warm up your sending — Start with low volume and gradually increase

What's the maximum email size?​

10MB including all attachments.

Can I send HTML emails?​

Yes. Provide the html field in your email request. We recommend also including a text field as a plain text fallback.

How does open/click tracking work?​

When enabled, Zyphr inserts a tracking pixel for opens and rewrites links for click tracking. Disable per-message with track_opens: false and track_clicks: false.

Push Notifications​

Push notifications aren't being delivered​

  1. Check credentials — Verify APNs/FCM credentials in Settings > Push Credentials
  2. Check device registration — Confirm the device is registered with a valid token
  3. Check token validity — Expired or invalidated tokens are automatically unregistered
  4. Check user preferences — The subscriber may have disabled push notifications

How do I handle token refresh?​

Re-register the device with the new token. Zyphr will update the existing device record if the same device_id is used.

SMS​

Why do I need to configure Twilio separately?​

Zyphr uses your Twilio account for SMS delivery. This gives you full control over your phone numbers, messaging service, and Twilio billing.

What phone number format should I use?​

Always use E.164 format: +[country code][number]. For example, US numbers should be +14155551234.

How are SMS segments counted?​

Standard ASCII messages allow 160 characters per segment. Unicode messages (emojis, non-Latin characters) allow 70 characters. Multi-part messages have slightly lower per-segment limits due to header overhead.

In-App Inbox​

How does real-time delivery work?​

The React component (@zyphr/inbox-react) connects via WebSocket. When you send a notification through the API, it's delivered to the user's inbox in real-time.

Can I use the inbox without React?​

Yes. The REST API endpoints are available for any frontend. See the In-App Messaging section for the full endpoint list.

Templates​

What templating language do you use?​

Handlebars. You can use variables ({{name}}), conditionals ({{#if ...}}), loops ({{#each ...}}), and helpers.

Can I preview a template before sending?​

Yes. Use the render endpoint:

curl -X POST https://api.zyphr.dev/v1/templates/welcome-email/render \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "John", "premium": true}'

Rate Limiting​

I'm getting 429 responses​

You've exceeded your plan's rate limit. Solutions:

  1. Implement exponential backoff with retries
  2. Use batch endpoints to reduce request count
  3. Upgrade your plan for higher limits

What are the rate limits?​

PlanRequests/second
Free10
Pro100
EnterpriseCustom

Webhooks​

How do I verify webhook signatures?​

Every webhook delivery is signed with HMAC-SHA256. Verify the signature using the webhook-signature header (Standard Webhooks format) or X-Zyphr-Signature header (legacy format). See Security & Signatures for full verification examples.

Webhook deliveries are failing​

  1. Check your endpoint — Must return 2xx within 30 seconds
  2. Check the URL — Must be HTTPS in production
  3. Check firewall rules — Ensure Zyphr's IPs can reach your endpoint
  4. Review delivery logs — Dashboard > Webhooks > Deliveries shows failure details

Can I retry failed webhook deliveries?​

Yes. Use the API or dashboard to retry individual deliveries:

curl -X POST https://api.zyphr.dev/v1/webhooks/wh_abc/deliveries/del_xyz/retry \
  -H "X-API-Key: zy_live_your_key"

Troubleshooting​

Where can I find request logs?​

The Zyphr Dashboard shows delivery logs for all channels under the Messages section.

How do I contact support?​