Email Setup Guide

Email is configured as a channel on a sender profile, sending from a domain you own and verify. No identity verification is needed to send email: a verified domain and your plan's quota are all it takes.

Prerequisites

Before setting up email, you need a sender profile. If you don't have one yet:

1. Go to Sender Profiles in the dashboard
2. Click New Sender and give it a name
3. Once created, click on the sender to open its settings

---

Sandbox email is no longer available

Sandbox domains (*.sandbox.zavu.dev) have been retired. Every email channel sends from a domain you own. A sender still configured with a sandbox domain must be reconfigured with a verified domain to keep sending; the steps below cover it.

---

Custom Domain Email

Add your own domain to send from addresses like noreply@yourcompany.com.

1. Add your domain

   Domains are managed under Accounts, so one domain can serve several senders. Add your domain there (e.g., yourcompany.com). The Email channel dialog links to it with Go to Accounts to add a domain when the project has none yet.

2. Configure DKIM records

   Open the domain's DNS panel. It lists the DKIM CNAME records to add at your DNS provider, formatted for that provider. Copy each record and add it:

   

   The records look like:

   CodeCopy
   selector1._domainkey.yourcompany.com  CNAME  selector1.dkim.zavu.dev
   selector2._domainkey.yourcompany.com  CNAME  selector2.dkim.zavu.dev
   selector3._domainkey.yourcompany.com  CNAME  selector3.dkim.zavu.dev

3. Wait for verification

   Verification runs automatically in the background once the records propagate; you can close the dialog and Zavu notifies you when it is done. Once verified, the domain status changes to Verified and the from address fields appear.

4. Select the domain on your sender

   Go to Sender Profiles > your sender > Channels tab > click the Email card, and pick the domain under Email Domain.

5. Configure from address

   Set your:

   • From Email Address: e.g., noreply
   • From Name: e.g., Your Company
   • Reply-To Email (optional): e.g., support@yourcompany.com

6. Save

   Click Save to enable the email channel with your custom domain.

Send a Test Email

TypeScriptcURLCopy
import Zavu from "@zavudev/sdk";

const zavu = new Zavu({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.messages.send({
  to: "recipient@example.com",
  channel: "email",
  subject: "Test from Zavu",
  text: "If you see this, your email channel is working!",
});

console.log("Message ID:", result.message.id);
console.log("Status:", result.message.status);

Create an email sender via the API

Once a domain is verified (dashboard or above), you can create an email sender programmatically — no phone number required. Set emailAddress to a from-address at your verified domain:

cURLTypeScriptCopy
curl -X POST https://api.zavu.dev/v1/senders \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transactional",
    "emailAddress": "noreply@yourdomain.com",
    "emailFromName": "Your Company",
    "setAsDefault": true
  }'

The address's domain must already be verified in your project. emailDomainId is optional — Zavu resolves it from the address. To attach an email address to an existing sender instead, PATCH /v1/senders/{senderId} with the same emailAddress field.

Then send from it — as the default sender, or by passing its ID in the Zavu-Sender header:

cURLCopy
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "user@example.com", "channel": "email", "subject": "Hi", "text": "Hello!" }'

---

Receiving Emails

Zavu can receive inbound emails and deliver them to your application via webhooks. Your domain needs an MX record for it.

Add the MX record

1. Open the Email channel dialog

   Go to your sender > Channels > Email card.

2. Find the MX record section

   Under Enable Email Receiving, Zavu shows the MX record to add to your DNS:

   CodeCopy
   yourcompany.com  MX  10  inbound.zavu.dev

3. Verify MX record

   After adding the record, click Verify MX. Once verified, the toggle becomes available.

4. Enable receiving

   Toggle Enable Email Receiving on and save.

Set Up Webhook for Inbound Emails

To receive inbound emails in your application, configure a webhook on your sender:

1. Go to your sender > Webhooks tab
2. Add your webhook URL and subscribe to the message.inbound event

Or via the API:

TypeScriptcURLCopy
await zavu.senders.update({
  senderId: "sender_abc123",
  webhookUrl: "https://api.yourcompany.com/webhooks/zavu",
  webhookEvents: ["message.inbound"],
});

When an email is received, Zavu sends a message.inbound event:

JSONCopy
{
  "id": "evt_1736850000000_abc123",
  "type": "message.inbound",
  "timestamp": 1736850000000,
  "senderId": "sender_abc123",
  "projectId": "proj_xyz789",
  "data": {
    "messageId": "msg_def456",
    "to": "support@yourcompany.com",
    "from": "customer@gmail.com",
    "channel": "email",
    "status": "received",
    "subject": "Question about my order",
    "text": "Hi, I have a question about order #12345..."
  }
}

Catch-all: receive every address at your domain

By default a sender only receives email sent to its exact address (e.g. support@yourcompany.com). Enable Catch-all to receive email addressed to any local part at the domain — sales@, billing@, hello@, or an address that doesn't exist as its own sender — all delivered through this one sender's webhook.

1. Enable receiving first

   Catch-all builds on receiving, so Enable Email Receiving must be on (the domain's MX record must be verified). See the steps above.

2. Toggle Catch-all

   In the sender's Channels > Email dialog, turn on Catch-all address and save. The toggle only appears once receiving is enabled.

Every catch-all message fires the same message.inbound event. Route sub-addresses yourself using data.to, which is always the original recipient:

JSONCopy
{
  "type": "message.inbound",
  "data": {
    "to": "sales@yourcompany.com",
    "from": "customer@gmail.com",
    "channel": "email",
    "subject": "Interested in a demo",
    "text": "..."
  }
}

You can also toggle catch-all from the API with emailCatchAllEnabled on the sender:

cURLCopy
curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emailReceivingEnabled": true, "emailCatchAllEnabled": true }'

---

Testing Your Setup

Verify Sending

1. Send a test email using the code examples above
2. Check the message status in Messages in the dashboard
3. Verify the email arrived in the recipient's inbox

Verify Receiving

1. Send an email to your configured address (e.g., support@yourcompany.com)
2. Check your webhook endpoint received the message.inbound event
3. Verify the inbound message appears in the dashboard under Messages

Common Issues

Next Steps

• Sending Emails - API reference for email messages
• Webhooks - Set up webhooks for delivery events
• Email Health - Monitor bounce rates and deliverability