Message Search

Search across all your notifications — emails, push notifications, SMS, and in-app messages — from a single endpoint. Full-text search with filtering, faceted counts, and result highlighting.

Overview

Feature	Description
Full-Text Search	Search message content, subjects, and metadata
Multi-Channel	Search across email, push, SMS, and in-app simultaneously
Filtering	Filter by channel, status, tags, date range, and metadata
Faceted Counts	Get filter counts for building search UIs
Highlighting	Matched terms highlighted in results
Suggestions	Autocomplete suggestions as users type

Quick Start

Search Messages

curl -X POST https://api.zyphr.dev/v1/search/messages \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "password reset",
    "channels": ["email"],
    "highlight": true
  }'

const results = await zyphr.search.messages({
  query: 'password reset',
  channels: ['email'],
  highlight: true,
});

Search API

POST Search (Full Options)

Use POST for complex queries with multiple filters:

curl -X POST https://api.zyphr.dev/v1/search/messages \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "welcome",
    "channels": ["email", "push"],
    "statuses": ["delivered", "sent"],
    "tags": ["onboarding"],
    "start_date": "2026-02-01T00:00:00Z",
    "end_date": "2026-02-28T23:59:59Z",
    "metadata": {
      "campaign": "february-launch"
    },
    "page": 1,
    "per_page": 25,
    "highlight": true
  }'

Search Parameters

Parameter	Type	Required	Description
query	string	Yes	Full-text search query
channels	string[]	No	Filter by channels: email, push, sms, in_app
statuses	string[]	No	Filter by delivery statuses
tags	string[]	No	Filter by message tags
start_date	string	No	Start of date range (ISO 8601)
end_date	string	No	End of date range (ISO 8601)
metadata	object	No	Filter by custom metadata key-value pairs
page	number	No	Page number (default: 1)
per_page	number	No	Results per page (default: 25, max: 100)
highlight	boolean	No	Highlight matched terms in results (default: false)

GET Search (Simple)

For simpler queries, use the GET endpoint with query parameters:

curl "https://api.zyphr.dev/v1/search/messages?q=welcome&channels=email,push&highlight=true&page=1&per_page=25" \
  -H "X-API-Key: zy_live_your_api_key"

Query Parameters

Parameter	Type	Description
q	string	Search query (required, min 1 character)
channels	string	Comma-separated channels
statuses	string	Comma-separated statuses
tags	string	Comma-separated tags
start_date	string	Start of date range
end_date	string	End of date range
page	number	Page number
per_page	number	Results per page
highlight	boolean	Enable highlighting

Response Format

{
  "data": {
    "results": [
      {
        "id": "msg_abc123",
        "channel": "email",
        "subject": "Welcome to Zyphr",
        "body_preview": "Thanks for signing up...",
        "status": "delivered",
        "recipient": "user@example.com",
        "created_at": "2026-02-15T10:30:00Z",
        "tags": ["onboarding"],
        "highlights": {
          "subject": "**Welcome** to Zyphr",
          "body": "Thanks for signing up to **Zyphr**..."
        }
      }
    ],
    "total": 142,
    "page": 1,
    "per_page": 25
  }
}

Faceted Search

Get filter counts alongside search results — ideal for building search UIs with dynamic filter counts:

curl -X POST https://api.zyphr.dev/v1/search/messages/faceted \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "welcome",
    "channels": ["email"]
  }'

Faceted Response

{
  "data": {
    "results": [...],
    "total": 142,
    "facets": {
      "channels": {
        "email": 98,
        "push": 32,
        "sms": 8,
        "in_app": 4
      },
      "statuses": {
        "delivered": 120,
        "sent": 15,
        "failed": 7
      },
      "tags": {
        "onboarding": 45,
        "transactional": 67,
        "marketing": 30
      }
    }
  }
}

Use facets to show users how many results match each filter option before they click.

Search Suggestions

Get autocomplete suggestions as users type:

curl "https://api.zyphr.dev/v1/search/suggestions?prefix=wel&limit=5" \
  -H "X-API-Key: zy_live_your_api_key"

Query Parameters

Parameter	Type	Required	Description
prefix	string	Yes	Search prefix (minimum 2 characters)
limit	number	No	Maximum suggestions (default: 10)

Response

{
  "data": {
    "suggestions": [
      "welcome email",
      "welcome series",
      "welcome back"
    ]
  }
}

Best Practices

Search Query Tips

• Use quotes for exact phrases: "password reset"
• Search is case-insensitive
• Combine with filters for precise results

Performance

• Use date range filters to narrow the search window
• Use channel filters when you know which channel to search
• Limit per_page to what you need — smaller pages are faster
• Use the GET endpoint for simple queries; POST for complex filters

Building Search UIs

1. Start with the suggestions endpoint for autocomplete
2. Use faceted search for the main results page with filter counts
3. Update facets as users apply filters to show remaining counts

API Reference

Method	Endpoint	Description
POST	/v1/search/messages	Full-text search with filters
GET	/v1/search/messages	Simple search with query params
POST	/v1/search/messages/faceted	Search with faceted counts
GET	/v1/search/suggestions	Autocomplete suggestions

Next Steps

• Message Replay - Replay failed messages found via search
• Webhooks Monitoring - Monitor delivery events
• Usage & Analytics - Track overall platform usage