Message Replay

Replay failed notifications — individually or in bulk — to recover from delivery failures. Preview messages before replaying, modify content on-the-fly, and retry across email, push, and SMS channels.

Overview

Feature	Description
Individual Replay	Retry a single failed message
Preview Before Replay	Inspect the message before resending
Content Modification	Change subject, body, or recipients on replay
Bulk Replay	Retry multiple failed messages at once
Failed Message Queries	Find messages eligible for replay

Quick Start

Replay a Failed Email

# 1. Preview the message
curl https://api.zyphr.dev/v1/replay/email/MSG_ID/preview \
  -H "X-API-Key: zy_live_your_api_key"

# 2. Replay it
curl -X POST https://api.zyphr.dev/v1/replay/email/MSG_ID \
  -H "X-API-Key: zy_live_your_api_key"

// Preview first
const preview = await zyphr.replay.preview('email', messageId);

// Then replay
await zyphr.replay.email(messageId);

Individual Replay

Replay an Email

Replay with the original content, or provide modifications:

curl -X POST https://api.zyphr.dev/v1/replay/email/MSG_ID \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "corrected-email@example.com",
    "subject": "Updated: Welcome to Zyphr"
  }'

// Replay with original content
await zyphr.replay.email(messageId);

// Replay with modifications
await zyphr.replay.email(messageId, {
  to: 'corrected-email@example.com',
  subject: 'Updated: Welcome to Zyphr',
});

Replay a Push Notification

curl -X POST https://api.zyphr.dev/v1/replay/push/MSG_ID \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated notification title"
  }'

Replay an SMS

curl -X POST https://api.zyphr.dev/v1/replay/sms/MSG_ID \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Updated message content"
  }'

Replay Parameters

All replay endpoints accept optional modification fields. Only provide fields you want to change — omitted fields retain the original values.

Email Modifications

Parameter	Type	Description
to	string	Override recipient email
subject	string	Override subject line
html	string	Override HTML body
text	string	Override plain text body

Push Modifications

Parameter	Type	Description
title	string	Override notification title
body	string	Override notification body
data	object	Override custom data payload

SMS Modifications

Parameter	Type	Description
to	string	Override recipient phone number
body	string	Override message body

Preview Before Replay

Inspect the message content before replaying:

curl https://api.zyphr.dev/v1/replay/email/MSG_ID/preview \
  -H "X-API-Key: zy_live_your_api_key"

curl https://api.zyphr.dev/v1/replay/push/MSG_ID/preview \
  -H "X-API-Key: zy_live_your_api_key"

curl https://api.zyphr.dev/v1/replay/sms/MSG_ID/preview \
  -H "X-API-Key: zy_live_your_api_key"

The preview returns the full message content, recipient details, and the original failure reason.

Finding Failed Messages

List Failed Messages

Query for messages eligible for replay:

curl "https://api.zyphr.dev/v1/replay/failed?channel=email&start_date=2026-02-01&end_date=2026-02-28&limit=50" \
  -H "X-API-Key: zy_live_your_api_key"

Query Parameters

Parameter	Type	Required	Description
channel	string	Yes	Channel: email, push, sms
status	string	No	Filter by failure status
start_date	string	No	Start of date range (ISO 8601)
end_date	string	No	End of date range (ISO 8601)
limit	number	No	Results per page (default: 25)
skip_permanent_failures	boolean	No	Exclude permanently failed messages

Count Failed Messages

Get a count of failed messages by channel:

curl "https://api.zyphr.dev/v1/replay/failed/count?channel=email&start_date=2026-02-01&end_date=2026-02-28" \
  -H "X-API-Key: zy_live_your_api_key"

Bulk Replay

Retry multiple failed messages at once:

curl -X POST https://api.zyphr.dev/v1/replay/bulk \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "message_ids": ["msg_001", "msg_002", "msg_003"]
  }'

await zyphr.replay.bulk({
  channel: 'email',
  messageIds: ['msg_001', 'msg_002', 'msg_003'],
});

warning

Bulk replay processes messages asynchronously. Large batches may take time to complete. Monitor delivery status through the message history endpoints or webhooks.

Bulk Replay by Date Range

You can also replay all failed messages within a date range:

curl -X POST https://api.zyphr.dev/v1/replay/bulk \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "start_date": "2026-02-01T00:00:00Z",
    "end_date": "2026-02-01T23:59:59Z",
    "skip_permanent_failures": true
  }'

Best Practices

• Preview before replaying - Always check the message content before resending
• Skip permanent failures - Use skip_permanent_failures to exclude hard bounces, invalid numbers, etc.
• Monitor after bulk replay - Watch delivery status via webhooks or the messages endpoint
• Use date ranges - When dealing with outages, replay all failures within the affected window
• Idempotency - Replayed messages are new deliveries with new message IDs

API Reference

Method	Endpoint	Description
POST	/v1/replay/email/:id	Replay an email
POST	/v1/replay/push/:id	Replay a push notification
POST	/v1/replay/sms/:id	Replay an SMS
GET	/v1/replay/:channel/:id/preview	Preview message for replay
GET	/v1/replay/failed	List failed messages
GET	/v1/replay/failed/count	Count failed messages
POST	/v1/replay/bulk	Bulk replay failed messages

Next Steps

• Message Search - Find specific messages to replay
• Webhooks Delivery - Track delivery status of replayed messages
• Error Codes - Understand failure reasons