Sending Emails

Email is ideal for rich content delivery, transactional notifications, and messages that need to be referenced later.

When to Use Email

Transactional emails: Order confirmations, receipts, shipping updates
Account notifications: Password resets, security alerts, welcome emails
Rich content: HTML formatting, images, detailed information
File attachments: Invoices, receipts, reports, documents (up to 40MB)
Asynchronous communication: Messages that don’t require immediate attention

Email operates as a separate channel and does not participate in smart routing. You must explicitly specify channel: "email" or send to an email address.

Sending an Email

const result = await zavu.messages.send({
  to: "user@example.com",
  channel: "email",
  subject: "Your order has shipped",
  text: "Hi John, your order #12345 has shipped and will arrive in 2-3 business days."
});

result = zavu.messages.send(
    to="user@example.com",
    channel="email",
    subject="Your order has shipped",
    text="Hi John, your order #12345 has shipped and will arrive in 2-3 business days."
)

result = client.messages.send(
  to: "user@example.com",
  channel: "email",
  subject: "Your order has shipped",
  text: "Hi John, your order #12345 has shipped and will arrive in 2-3 business days."
)

result, _ := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
	To:      zavudev.String("user@example.com"),
	Channel: zavudev.String("email"),
	Subject: zavudev.String("Your order has shipped"),
	Text:    zavudev.String("Hi John, your order #12345 has shipped and will arrive in 2-3 business days."),
})

<?php
$result = $client->messages->send([
    'to' => 'user@example.com',
    'channel' => 'email',
    'subject' => 'Your order has shipped',
    'text' => 'Hi John, your order #12345 has shipped and will arrive in 2-3 business days.',
]);

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "channel": "email",
    "subject": "Your order has shipped",
    "text": "Hi John, your order #12345 has shipped and will arrive in 2-3 business days."
  }'

You can optionally specify a sender by passing zavuSender (TypeScript), zavu_sender (Python), or the Zavu-Sender header (cURL). If omitted, your project’s default sender is used.

HTML Emails

Send rich HTML emails by including htmlBody. The text field serves as the plain-text fallback:

const result = await zavu.messages.send({
  to: "user@example.com",
  channel: "email",
  subject: "Welcome to Zavu",
  text: "Welcome to Zavu! We are excited to have you on board.",
  htmlBody: `
    <h2>Welcome to Zavu!</h2>
    <p>We are excited to have you on board.</p>
    <a href="https://dashboard.zavu.dev">Get Started</a>
  `,
  replyTo: "support@yourcompany.com"
});

result = zavu.messages.send(
    to="user@example.com",
    channel="email",
    subject="Welcome to Zavu",
    text="Welcome to Zavu! We are excited to have you on board.",
    html_body="""
        <h2>Welcome to Zavu!</h2>
        <p>We are excited to have you on board.</p>
        <a href="https://dashboard.zavu.dev">Get Started</a>
    """,
    reply_to="support@yourcompany.com"
)

result = client.messages.send(
  to: "user@example.com",
  channel: "email",
  subject: "Welcome to Zavu",
  text: "Welcome to Zavu! We are excited to have you on board.",
  html_body: "<h2>Welcome to Zavu!</h2><p>We are excited to have you on board.</p>",
  reply_to: "support@yourcompany.com"
)

result, _ := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
	To:       zavudev.String("user@example.com"),
	Channel:  zavudev.String("email"),
	Subject:  zavudev.String("Welcome to Zavu"),
	Text:     zavudev.String("Welcome to Zavu! We are excited to have you on board."),
	HTMLBody: zavudev.String("<h2>Welcome to Zavu!</h2><p>We are excited to have you on board.</p>"),
	ReplyTo:  zavudev.String("support@yourcompany.com"),
})

<?php
$result = $client->messages->send([
    'to' => 'user@example.com',
    'channel' => 'email',
    'subject' => 'Welcome to Zavu',
    'text' => 'Welcome to Zavu! We are excited to have you on board.',
    'htmlBody' => '<h2>Welcome to Zavu!</h2><p>We are excited to have you on board.</p>',
    'replyTo' => 'support@yourcompany.com',
]);

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "channel": "email",
    "subject": "Welcome to Zavu",
    "text": "Welcome to Zavu! We are excited to have you on board.",
    "htmlBody": "<h2>Welcome to Zavu!</h2><p>We are excited to have you on board.</p>",
    "replyTo": "support@yourcompany.com"
  }'

Attachments

Send files by including the attachments array. Each attachment can provide file content as base64 or a URL to fetch from.

Base64 Content

const fs = require("fs");
const content = fs.readFileSync("invoice.pdf").toString("base64");

const result = await zavu.messages.send({
  to: "user@example.com",
  channel: "email",
  subject: "Your invoice",
  text: "Please find your invoice attached.",
  attachments: [
    {
      filename: "invoice.pdf",
      content: content,
      content_type: "application/pdf",
    },
  ],
});

import base64

with open("invoice.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode()

result = zavu.messages.send(
    to="user@example.com",
    channel="email",
    subject="Your invoice",
    text="Please find your invoice attached.",
    attachments=[
        {
            "filename": "invoice.pdf",
            "content": content,
            "content_type": "application/pdf",
        }
    ],
)

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "channel": "email",
    "subject": "Your invoice",
    "text": "Please find your invoice attached.",
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQK...",
        "content_type": "application/pdf"
      }
    ]
  }'

URL Path

Instead of encoding the file, provide a URL and Zavu will fetch it:

const result = await zavu.messages.send({
  to: "user@example.com",
  channel: "email",
  subject: "Your report",
  text: "Please find your report attached.",
  attachments: [
    {
      filename: "report.pdf",
      path: "https://your-server.com/reports/report.pdf",
    },
  ],
});

result = zavu.messages.send(
    to="user@example.com",
    channel="email",
    subject="Your report",
    text="Please find your report attached.",
    attachments=[
        {
            "filename": "report.pdf",
            "path": "https://your-server.com/reports/report.pdf",
        }
    ],
)

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "channel": "email",
    "subject": "Your report",
    "text": "Please find your report attached.",
    "attachments": [
      {
        "filename": "report.pdf",
        "path": "https://your-server.com/reports/report.pdf"
      }
    ]
  }'

Inline Images

Embed images directly in HTML using content_id:

const result = await zavu.messages.send({
  to: "user@example.com",
  channel: "email",
  subject: "Your weekly report",
  text: "See your weekly report.",
  htmlBody: `
    <h2>Weekly Report</h2>
    <img src="cid:chart" alt="Performance chart" />
    <p>Your performance improved 15% this week.</p>
  `,
  attachments: [
    {
      filename: "chart.png",
      path: "https://your-server.com/charts/weekly.png",
      content_type: "image/png",
      content_id: "chart",
    },
  ],
});

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "channel": "email",
    "subject": "Your weekly report",
    "text": "See your weekly report.",
    "htmlBody": "<h2>Weekly Report</h2><img src=\"cid:chart\" /><p>Improved 15%.</p>",
    "attachments": [
      {
        "filename": "chart.png",
        "path": "https://your-server.com/charts/weekly.png",
        "content_type": "image/png",
        "content_id": "chart"
      }
    ]
  }'

Attachment Fields

Field	Required	Description
`filename`	Yes	Name of the file
`content`	One of	Base64-encoded file content
`path`	One of	URL to fetch the file from
`content_type`	No	MIME type (auto-detected from filename if omitted)
`content_id`	No	ID for inline images, reference in HTML as `cid:your_id`

Each attachment must have either content or path, not both. Total attachment size is limited to 40MB per email, and a maximum of 50 attachments per message.

Request Fields

Field	Required	Description
`to`	Yes	Valid email address
`channel`	Yes	Must be `"email"`
`subject`	Yes	Email subject line (max 998 chars)
`text`	Yes	Plain text body
`htmlBody`	No	HTML version of the email
`replyTo`	No	Reply-To email address
`attachments`	No	Array of file attachments (email only)

Channel Detection

If you send to an email address without specifying a channel, Zavu automatically selects email:

const result = await zavu.messages.send({
  to: "user@example.com",
  subject: "Hello",
  text: "This will be sent as email automatically"
});

result = zavu.messages.send(
    to="user@example.com",
    subject="Hello",
    text="This will be sent as email automatically"
)

result = client.messages.send(
  to: "user@example.com",
  subject: "Hello",
  text: "This will be sent as email automatically"
)

result, _ := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
	To:      zavudev.String("user@example.com"),
	Subject: zavudev.String("Hello"),
	Text:    zavudev.String("This will be sent as email automatically"),
})

<?php
$result = $client->messages->send([
    'to' => 'user@example.com',
    'subject' => 'Hello',
    'text' => 'This will be sent as email automatically',
]);

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "text": "This will be sent as email automatically"
  }'

Setting Up Email

Before sending emails, you need to configure your sender with a verified domain.

1. Add Your Domain

Go to Email Domains in the dashboard and add your domain (e.g., yourcompany.com).

2. Configure DNS

Add the DKIM records provided by Zavu to your DNS:

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

DNS propagation typically takes a few minutes, but can take up to 48 hours in some cases.

3. Verify Domain

Zavu automatically checks your DNS records every 5 minutes. Once verified, your domain status will change to verified.

4. Assign to Sender

Assign the verified domain to a sender and configure your from address:

From address: noreply@yourcompany.com
Reply-To address: support@yourcompany.com (optional)

Delivery Status

Check message status by ID:

const result = await zavu.messages.get({ messageId: "msg_abc123" });
console.log("Status:", result.message.status);

result = zavu.messages.get(message_id="msg_abc123")
print(f"Status: {result.message.status}")

result = client.messages.get(message_id: "msg_abc123")
puts "Status: #{result.message.status}"

result, _ := client.Messages.Get(context.TODO(), "msg_abc123")
fmt.Println("Status:", result.Message.Status)

<?php
$result = $client->messages->get('msg_abc123');
echo "Status: " . $result->message->status;

curl https://api.zavu.dev/v1/messages/msg_abc123 \
  -H "Authorization: Bearer $ZAVU_API_KEY"

Status	Description
`queued`	Accepted, pending delivery
`sending`	Being sent to recipient
`delivered`	Confirmed delivered
`failed`	Delivery failed

Common Errors

Error	Description	Solution
`subject_required`	Missing subject line	Include `subject` field
`sender_not_configured`	Sender lacks email setup	Configure email domain on sender
`domain_not_verified`	Domain not verified	Complete DNS verification
`bounce`	Email bounced	Invalid or non-existent email address
`complaint`	Marked as spam	Review email content and sending practices

Email vs SMS/WhatsApp

Feature	Email	SMS / WhatsApp
Smart Routing	No - explicit channel	Yes - auto-selected
Automatic Fallback	No	Yes
Recipient Type	Email address	Phone number (E.164)
Rich Content	Full HTML support	Limited (WhatsApp only)
File Attachments	Yes (up to 40MB)	Media only (WhatsApp)
Delivery Speed	Minutes	Seconds

Email is a separate channel and does not fall back to SMS/WhatsApp if delivery fails.

Best Practices

Always include plain text - Some email clients only show plain text
Use a verified domain - Improves deliverability and avoids spam filters
Set Reply-To - Make it easy for recipients to respond
Keep subjects clear - Descriptive subjects improve open rates
Test before sending - Preview HTML emails in multiple clients
Respect unsubscribes - Honor opt-out requests promptly

Compliance

Email messaging is regulated. Ensure you comply with CAN-SPAM, GDPR, and other applicable laws.

Requirements

Consent: Have permission before sending marketing emails
Unsubscribe: Include a working unsubscribe link
Sender identification: Clearly identify your business
Physical address: Include your business address (for marketing emails)
Honest subject lines: Don’t use deceptive subject lines

Example Compliant Email

<h2>Your Order Has Shipped!</h2>
<p>Hi John, your order #12345 has shipped.</p>
<p>Track your package: <a href="https://track.co/abc">View Tracking</a></p>

<hr>
<p style="font-size: 12px; color: #666;">
  YourCompany, Inc. | 123 Main St, San Francisco, CA 94102<br>
  <a href="https://yourcompany.com/unsubscribe">Unsubscribe</a>
</p>

Getting Started

Concepts

Guides

Sending Emails

When to Use Email

Sending an Email

HTML Emails

Attachments

Base64 Content

URL Path

Inline Images

Attachment Fields

Request Fields

Channel Detection

Setting Up Email

1. Add Your Domain

2. Configure DNS

3. Verify Domain

4. Assign to Sender

Delivery Status

Common Errors

Email vs SMS/WhatsApp

Best Practices

Compliance

Requirements

Example Compliant Email

​When to Use Email

​Sending an Email

​HTML Emails

​Attachments

​Base64 Content

​URL Path

​Inline Images

​Attachment Fields

​Request Fields

​Channel Detection

​Setting Up Email

​1. Add Your Domain

​2. Configure DNS

​3. Verify Domain

​4. Assign to Sender

​Delivery Status

​Common Errors

​Email vs SMS/WhatsApp

​Best Practices

​Compliance

​Requirements

​Example Compliant Email

When to Use Email

Sending an Email

HTML Emails

Attachments

Base64 Content

URL Path

Inline Images

Attachment Fields

Request Fields

Channel Detection

Setting Up Email

1. Add Your Domain

2. Configure DNS

3. Verify Domain

4. Assign to Sender

Delivery Status

Common Errors

Email vs SMS/WhatsApp

Best Practices

Compliance

Requirements

Example Compliant Email