Quick Navigation

Need an API Key?

v1.0 ProductionLast updated: 2 days ago

API Documentation

Welcome to the ZorroFlow Mail API. Build powerful email features into your application with our RESTful interface. All endpoints are prefixed with https://api.zorroflow.com/v1.

Already have an account?

View personalized API documentation with examples using your domain and quick access to your API keys.

View Dashboard API Docs →

Authentication

The ZorroFlow API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard. Authentication to the API is performed via Bearer Auth. Provide your API key as the basic auth password value. You do not need to provide a username.

bash

curl https://api.zorroflow.com/v1/emails \
  -H "Authorization: Bearer zf_live_..." \
  -H "Content-Type: application/json"

React Email SDK

Stop wrestling with HTML tables. Use our Node.js SDK to write emails using modern React components. We handle the rendering and compatibility for all major email clients.

Installation

npm install @zorroflow/react-sdk zorroflow

Usage

send-email.tsx

import { Zorro } from 'zorroflow';
import WelcomeEmail from './emails/welcome';

const client = new Zorro(process.env.ZORRO_API_KEY);

await client.emails.send({
  to: 'user@example.com',
  subject: 'Welcome Aboard',
  react: <WelcomeEmail firstName="John" />
});

Rate Limits

API rate limits are applied per API key. The returned HTTP headers of any API request show your current rate limit status.

Header	Description
X-RateLimit-Limit	The maximum number of requests available in the current time frame.
X-RateLimit-Remaining	The number of requests remaining in the current time frame.
X-RateLimit-Reset	A timestamp of when the rate limit will reset.

Transactional EmailsVERIFIED

Send transactional emails like OTC codes, password resets, notifications, receipts, and alerts. These endpoints are production-ready and fully tested.

POST

Send Transactional Email`/api/v1/transactional/send`

Send automated system emails ONLY (OTC codes, password resets, notifications). NOT for user-composed emails - use /api/v1/send-email instead. Transactional emails are simpler, single-recipient only, and auto-expire after 24 hours.

Name	Type	Required	Description
from	string \| object	No	Sender address. Defaults to noreply@{yourdomain}. Must match API key domain. Use object for custom name: { email: "...", name: "..." }
to	string \| object	Yes	Recipient email address
subject	string	Yes	Email subject line
html	string	Yes	HTML body content
text	string	No	Plain text body content
metadata	object	No	Custom metadata (stored with email for tracking)
tags	array	No	Tags for categorization and analytics
attachments	array	No	File attachments (base64 or URL)

Core Email Operations

GET

List Emails`/api/v1/emails`

Retrieve a paginated list of emails for your domain with filtering, sorting, and conversation threading support. Use threading parameters to group related emails into conversations.

Name	Type	Required	Description
page	number	No	Page number for pagination (default: 1)
limit	number	No	Number of emails per page (default: 50, max: 100)
direction	string	No	Filter by direction: "inbound" or "outbound"
isStarred	boolean	No	Filter starred emails
isRead	boolean	No	Filter read/unread emails
folder	string	No	Filter by folder: "inbox", "sent", "archive", "trash"
threadId	string	No	Filter emails by conversation thread ID (returns all messages in the thread)
view	string	No	View mode: "flat" (default - all emails), "threaded" (grouped by conversation), "expanded" (with thread metadata)
includeThreadInfo	boolean	No	Include additional threading metadata in response (message position, thread size, etc.)

GET

Retrieve Email`/api/v1/emails/{id}`

Get the full details of a specific email message, including complete body content and metadata.

Name	Type	Required	Description
id	string	Yes	The unique identifier of the email message

PATCH

Update Email`/api/v1/emails/{id}`

Update email properties such as read status, starred status, importance, folder, and labels. Perfect for marking emails as read/unread, starring messages, or organizing your inbox.

Name	Type	Required	Description
id	string	Yes	The unique identifier of the email message
isRead	boolean	No	Mark as read (true) or unread (false)
isStarred	boolean	No	Toggle starred status
isImportant	boolean	No	Mark as important
isArchived	boolean	No	Archive the email
folder	string	No	Move to folder: "inbox", "sent", "archive", "trash"
labels	array	No	Array of label strings to assign

PATCH

Batch Update Emails`/api/v1/emails/batch`

Update multiple emails in a single request for improved performance. Perfect for bulk actions like marking multiple emails as read, starring selections, or batch archiving. Uses MongoDB bulkWrite for efficiency and reduces 10 requests to 1 (10x faster).

Name	Type	Required	Description
updates	array	Yes	Array of update objects (max 100)
updates[].id	string	Yes	Email ID to update
updates[].updates	object	Yes	Fields to update (isRead, isStarred, isImportant, isArchived, folder, labels)

Thread Management

Webhooks

Subscribe to events to receive real-time updates about your email delivery and engagement.

Errors

Code	Meaning
400	Bad Request - The request was invalid or cannot be served.
401	Unauthorized - Missing or invalid API key.
403	Forbidden - The API key does not have permissions for this resource.
429	Too Many Requests - Rate limit exceeded.