Getting Started with EDITH Email API

Welcome to the EDITH Email Service API documentation. This guide will help you understand how to effectively integrate with our email infrastructure for sending, receiving, and managing emails at scale.

Overview

EDITH is a comprehensive email management platform that provides:

• Email Sending: Send transactional and marketing emails with advanced tracking
• Domain Management: Configure and verify sending domains with DKIM/SPF authentication
• Email Templates: Create reusable email templates for consistent messaging
• Inbound Email Processing: Receive and process incoming emails via webhooks
• SMTP/IMAP Integration: Connect your own mail servers for sending and receiving
• Webhooks: Real-time notifications for email events (delivery, opens, clicks, bounces)
• IP Pool Management: Dedicated IP pools for better deliverability control

---

Authentication

All API requests require authentication using one of the following methods:

Bearer Token Authentication

Most endpoints use Bearer token authentication. Include your API token in the request header:

Authorization: Bearer your_api_token_here

Example:

curl -X POST https://api.sparrowmailer.com/v1/email/send \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API Key Authentication

Some endpoints support API Key authentication:

X-API-Key: your_api_key_here

---

Base URL

All API endpoints are relative to a base URL. Production is:

https://api.sparrowmailer.com

Every example in these guides uses the production host. Non-production environments (staging, test) are served from different hosts — this documentation site is built once per environment, so the host shown on the home page and in the REST API reference is always the one for the environment you are reading. If that differs from the examples below, the home page is authoritative: swap the host and keep the path.

Paths, payloads and responses are identical across environments; only the host changes.

---

Request Format

• All request bodies must be JSON formatted
• Set the Content-Type header to application/json
• Use UTF-8 encoding for all text content

---

Response Format

All responses follow a consistent structure:

Success Response

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": "Error description",
  "details": "Additional error context (optional)"
}

---

HTTP Status Codes

Code	Description
200	Success - Request completed successfully
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing authentication
404	Not Found - Resource does not exist
409	Conflict - Resource already exists or state conflict
422	Unprocessable Entity - Validation failed
500	Internal Server Error - Server-side error

---

Rate Limiting

API requests are rate-limited to ensure fair usage:

• Standard tier: 100 requests per minute
• Enterprise tier: 1000 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699449600

---

Pagination

List endpoints support cursor-based pagination:

Parameter	Type	Description
pageSize	integer	Number of results per page (default: 20, max: 50)
pageToken	string	Cursor token for the next page of results

Example Request:

GET /v1/email/logs?pageSize=25&pageToken=eyJJZCI6IjEyMzQ1...

Response includes:

{
  "success": true,
  "data": [...],
  "nextPageToken": "eyJJZCI6IjY3ODkw...",
  "totalCount": 150
}

---

Quick Start: Send Your First Email

Step 1: Configure a Sending Domain

Before sending emails, you need to add and verify a sending domain:

curl -X POST https://api.sparrowmailer.com/v1/domain/add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mail.yourcompany.com"
  }'

Step 2: Add DNS Records

The response will include DNS records (DKIM, SPF) that you need to add to your domain's DNS settings.

Step 3: Verify the Domain

After adding DNS records, verify the domain:

curl -X PUT https://api.sparrowmailer.com/v1/domain/verify/mail.yourcompany.com \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 4: Send an Email

Once verified, you can send emails:

curl -X POST https://api.sparrowmailer.com/v1/email/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "sender@mail.yourcompany.com",
      "name": "Your Company"
    },
    "to": [
      {
        "email": "recipient@example.com",
        "name": "John Doe"
      }
    ],
    "subject": "Welcome to Our Service",
    "content": [
      {
        "type": "text/html",
        "value": "<h1>Welcome!</h1><p>Thank you for signing up.</p>"
      }
    ],
    "mailer_id": "your_mailer_id",
    "settings": {
      "open_tracking": { "enable": true },
      "click_tracking": { "enable": true }
    }
  }'

---

Key Concepts

Mailer ID

A mailer_id is a unique identifier for your email configuration. It's returned when you:

• Add a sending domain
• Configure SMTP/IMAP settings
• Set up OAuth email connections

You must include the mailer_id when sending emails to specify which configuration to use.

Email Statuses

Status values are uppercase and matched exactly when filtering email logs:

Status	Description
QUEUED	Accepted and queued for sending
FAILED	The send attempt failed
MAIL_DELIVERED	Recipient's mail server accepted the email
MAIL_OPENED	Recipient opened the email
MAIL_CLICKED	Recipient clicked a link in the email
MAIL_BOUNCE	Email bounced (soft or hard bounce)
MAIL_UNSUBSCRIBED	Recipient unsubscribed

Template Variables

Use double curly braces for dynamic content in templates:

<p>Hello {{name}},</p>
<p>Your order #{{order_id}} has been shipped!</p>

Pass substitutions when sending:

{
  "substitutions": {
    "recipient@example.com": {
      "name": "John",
      "order_id": "12345"
    }
  }
}

---

SDKs and Libraries

We provide official SDKs for JS:

• JS: npm install @sparrowengg/sparrow-mailer-sdk@0.1.2-stable.0