# Easy Way

> The simplest way to send messages with Zavu

Send your first message in seconds. Zavu handles channel selection, delivery optimization, and fallbacks automatically.

## Quick Start

```typescript
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Hello from Zavu!",
});
```

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "text": "Hello from Zavu!"
  }'
```

> **Tip:**
> You can optionally specify a sender by passing `"Zavu-Sender": "snd_abc123"` inside the send params (TypeScript), or the `Zavu-Sender` header (cURL). If omitted, your project's default sender is used.

That's it. Zavu automatically:
- **Respects user preference**: When a user messages you first, we reply on the same channel they used
- **Optimizes outbound**: For business-initiated messages, selects the optimal channel based on cost and delivery rates
- **Falls back intelligently**: Tries alternative channels if delivery fails
- **Tracks everything**: Delivery status updates via API and webhooks

## How It Works

When you send a message without specifying a channel, your **default Sender** handles routing:

```
Your Message → Default Sender → Smart Routing → Best Channel → Delivery
```

### Senders

A Sender is a configuration that defines how messages are sent. Each Sender has:

- **Channels**: Which channels are available (SMS, WhatsApp, etc.)
- **Routing Policy**: `smart` (automatic) or `manual` (you choose)
- **Phone Numbers**: Configured for each channel

> **Tip:**
> Create your first Sender in the [Dashboard](https://dashboard.zavu.dev/senders) or via the [API](https://www.zavu.dev/docs/api-reference/senders/create).

## Using a Specific Sender

If you have multiple Senders (e.g., "Marketing" and "Support"), specify which one to use:

```typescript
const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Your order has shipped!",
  "Zavu-Sender": "snd_abc123",
});
```

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Zavu-Sender: snd_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "text": "Your order has shipped!"
  }'
```

## Specifying a Channel

For full control, specify the channel directly:

```typescript
const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Hello!",
  channel: "whatsapp",
});
```

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "text": "Hello!",
    "channel": "whatsapp"
  }'
```

Available channels: `sms`, `whatsapp`

## Response

A successful request returns the message details:

```json
{
  "message": {
    "id": "msg_abc123",
    "to": "+14155551234",
    "text": "Hello from Zavu!",
    "channel": "whatsapp",
    "status": "queued",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}
```

| Status | Description |
|--------|-------------|
| `queued` | Message accepted, pending delivery |
| `sent` | Sent to carrier/provider |
| `delivered` | Confirmed delivered |
| `read` | User opened the message (WhatsApp only) |
| `failed` | Delivery failed |

## Next Steps

- [Smart Routing](https://www.zavu.dev/docs/guides/sending-messages/smart-routing) - Learn how automatic channel selection saves up to 90% on messaging costs
- [SMS Guide](https://www.zavu.dev/docs/guides/sending-messages/sms) - SMS-specific features and best practices
- [WhatsApp Guide](https://www.zavu.dev/docs/guides/whatsapp/overview) - Rich messaging with media, buttons, and templates

## API Reference

- [Send a message](https://www.zavu.dev/docs/api-reference/send-a-message) — full HTTP reference for the `/v1/messages` endpoint
- [Get a message by ID](https://www.zavu.dev/docs/api-reference/get-message-by-id) — retrieve delivery status and metadata
- [List messages](https://www.zavu.dev/docs/api-reference/list-messages) — fetch sent messages with filtering and pagination