Eclatrecon AI Mail API

Complete REST API for programmatic email management, webhooks, and automation.

BASE URL

http://localhost:3001/api

PUBLIC API

/api/v1/*

FORMAT

JSON (application/json)

Quick Start

# 1. Generate an API
                            key (use your JWT token)
                        curl -X POST http://localhost:3001/api/v1/keys \
                        -H "Authorization: Bearer YOUR_JWT_TOKEN" \
                        -H "Content-Type: application/json" \
                        -d '{"name":"My App","permissions":"full"}'

                        # 2. Use the API key
                        curl http://localhost:3001/api/v1/emails \
                        -H "X-API-Key: nm_your_api_key_here"

                        # 3. Send an email
                        curl -X POST http://localhost:3001/api/v1/emails/send \
                        -H "X-API-Key: nm_your_api_key_here" \
                        -H "Content-Type: application/json" \
                        -d '{"to":"user@example.com","subject":"Hello","bodyText":"Hi!"}'
                    

Authentication

Eclatrecon AI Mail supports two authentication methods:

1. JWT Token Internal

Used by the frontend. Obtain via login/signup endpoints.

POST /api/auth/login
                            { "email": "user@example.com", "password": "secret" }
                            → { "token": "eyJ...", "user": { ... } }

                            # Use in requests:
                            Authorization: Bearer eyJ...
                        

2. API Key Public API

For external integrations. Generate via the API or Settings page.

# Via header
                                (recommended):
                            X-API-Key: nm_abc123def456...

                            # Via query parameter:
                            GET /api/v1/emails?api_key=nm_abc123def456...
                        

API Keys

Manage API keys for programmatic access. Requires JWT authentication.

POST/api/v1/keys

Generate a new API key

Param	Type	Required	Description
name	string	✓	Key name
permissions	string		`read` / `write` / `send` / `full` (comma-separated)
expiresInDays	number		Key expires after N days (null = never)

Response:
                            { "id": "uuid", "key": "nm_abc123...", "prefix": "nm_abc123",
                            "permissions": "full", "expiresAt": null }

GET/api/v1/keys

List your API keys (keys are masked)

DELETE/api/v1/keys/:id

Revoke an API key

Rate Limits

API keys have a default rate limit of 100 requests/hour. Admin can configure per-key limits. The response headers include:

X-RateLimit-Limit: 100
                        X-RateLimit-Remaining: 97
                        X-RateLimit-Reset: 1699999999

Emails API Key

GET/api/v1/emails

List emails in a folder. Permission: read

Query Param	Default	Description
folder	inbox	inbox, sent, drafts, spam, trash
page	1	Page number
limit	50	Results per page
unread		Set `true` for unread only
search		Search in subject/from

GET/api/v1/emails/:id

Get full email details with attachments. Permission: read

POST/api/v1/emails/send

Send an email via SMTP. Permission: send

Body	Required	Description
to	✓	Recipient email(s)
subject	✓	Email subject
bodyText		Plain text body
bodyHtml		HTML body
cc, bcc		CC/BCC addresses

PUT/api/v1/emails/:id

Update email (read/star/move). Permission: write

Body	Description
isRead	true/false
isStarred	true/false
folder	Move to folder: inbox, spam, trash

DELETE/api/v1/emails/:id

Permanently delete an email. Permission: write

Contacts API Key

GET/api/v1/contacts

List all contacts

POST/api/v1/contacts

Create a contact. Body: name, email, phone, company, notes

DELETE/api/v1/contacts/:id

Delete a contact

Folders & Labels API Key

GET/api/v1/folders

List folders with email counts and unread counts

GET/api/v1/labels

List all labels

Search API Key

GET/api/v1/search?q=keyword

Full-text search across emails (subject, body, sender). Uses FTS5 index.

Query	Description
q	Search query (required)
limit	Max results (default: 20)

Account API Key

GET/api/v1/me

Get your account info

GET/api/v1/account/stats

Get storage, email count, unread count, contact count

Signatures JWT

GET/api/signatures

List your email signatures

POST/api/signatures

Create a signature. Body: name, bodyHtml, bodyText, isDefault

PUT/api/signatures/:id

Update a signature

DELETE/api/signatures/:id

Delete a signature

Email Templates JWT

GET/api/templates

List templates

POST/api/templates

Create template. Body: name, subject, bodyHtml, bodyText, category

PUT/api/templates/:id

Update template

DELETE/api/templates/:id

Delete template

Scheduled Send JWT

Schedule emails to be sent at a future date/time. A background worker checks every 60 seconds.

GET/api/scheduled

List scheduled emails

POST/api/scheduled

Schedule an email

{ "to": "user@example.com", "subject":
                            "Reminder",
                            "bodyText": "Don't forget!", "sendAt": "2026-03-15T09:00:00Z" }

DELETE/api/scheduled/:id

Cancel a pending scheduled email

Contact Groups JWT

GET/api/contact-groups

List groups with member counts

POST/api/contact-groups

Create group. Body: name, description

GET/api/contact-groups/:id/members

List group members

POST/api/contact-groups/:id/members

Add member. Body: contactId

DELETE/api/contact-groups/:id/members/:contactId

Remove member

DELETE/api/contact-groups/:id

Delete group

Forwarding Rules JWT

GET/api/forwarding

List forwarding rules

POST/api/forwarding

Create rule. Body: forwardTo, keepCopy, conditionFrom, conditionSubject

PUT/api/forwarding/:id/toggle

Toggle rule on/off

DELETE/api/forwarding/:id

Delete rule

Export JWT

GET/api/export/emails?folder=inbox&format=json

Export emails as JSON or EML file download

Param	Options
folder	inbox, sent, drafts, spam, trash
format	`json` or `eml`

Webhooks

Receive real-time notifications when events happen in Nothing Mail.

POST/api/v1/webhooks

Register a webhook endpoint

{ "url": "https://myapp.com/webhook",
                            "events": ["email.received", "email.sent"] }

                            Response:
                            { "id": "uuid", "secret": "whsec_abc123...",
                            "message": "Save the secret — used to verify signatures" }
                        

GET/api/v1/webhooks

List webhooks

GET/api/v1/webhooks/:id/logs

View delivery logs (last 50)

PUT/api/v1/webhooks/:id/toggle

Enable/disable webhook

DELETE/api/v1/webhooks/:id

Delete webhook

Webhook Events

Event	Triggered When	Payload
email.received	New email arrives via IMAP	emailId, from, subject
email.sent	Email sent via SMTP or API	emailId, to, subject
email.deleted	Email permanently deleted	emailId
email.read	Email marked as read	emailId
email.starred	Email starred/unstarred	emailId, isStarred
email.scheduled_sent	Scheduled email was sent	emailId, subject
contact.created	New contact added	contactId, name, email
contact.deleted	Contact deleted	contactId
*	All events (wildcard)	varies

Webhook Verification

Each webhook delivery includes an HMAC-SHA256 signature. Verify it to ensure authenticity:

// Headers sent with
                            each webhook:
                        X-Webhook-Signature: <hmac_sha256_hex>
                        X-Webhook-Event: email.received

                        // Node.js verification example:
                        const crypto = require('crypto');
                        const signature = req.headers['x-webhook-signature'];
                        const expected = crypto
                        .createHmac('sha256', YOUR_WEBHOOK_SECRET)
                        .update(JSON.stringify(req.body))
                        .digest('hex');

                        if (signature === expected) {
                        console.log('✓ Webhook verified');
                        }
                    

Admin API Admin Only

All admin endpoints require JWT auth + admin role. Base: /api/admin

GET /stats

Dashboard statistics

GET /users

List all users

POST /users

Create user

PUT /users/:id

Update user

DELETE /users/:id

Delete user

PUT /users/:id/reset-password

Reset password

PUT /users/:id/toggle-admin

Toggle admin role

GET /emails

Browse all emails

GET /accounts

All mail accounts

GET /sessions

All sessions

GET /storage

Storage breakdown

GET /logs

Audit logs

GET /health

Server health

POST /broadcast

Message all users

POST /block-sender

Block sender

POST /bootstrap

First admin setup

Lead Scraper APIFY

Scrape leads from any website, Google Maps, LinkedIn, and more using Apify — then import them directly into your subscriber lists for email campaigns.

1

Get Your Apify API Token

Sign up for free at apify.com, then go to Settings → Integrations to copy your API token.

2

Save Token in Settings

Navigate to Lead Scraper in the sidebar, click ⚙ Settings, paste your token, and click Save Settings.

3

Start a Scrape

Click 🔍 New Scrape, pick a scraper type (e.g., Website Contacts or Google Maps), enter a URL or keyword, select a target list or create a new one, and hit Start Scraping.

4

Use Leads in Campaigns

Once the scrape completes, leads are auto-imported (if enabled). Or use Import or Quick Campaign to instantly create an email campaign with merge tags like {{first_name}}.

Settings Configuration

Setting	Description	Default
apify_token	Your personal Apify API token from console.apify.com	empty
auto_import	Automatically import scraped leads into the target subscriber list	On
default_actor	Default scraper type when opening the scrape form	website-contacts

Key Features

person_search

8 Scrapers

Website contacts, Google Maps, LinkedIn, Yellow Pages, Instagram, Twitter, and custom actors.

upload

Auto Import

Leads auto-import into subscriber lists with email, name, company, phone data.

campaign

Quick Campaign

One-click campaign creation from any scrape job — with merge tag support.

download

CSV Export

Export all leads to CSV with email, name, company, phone, website, LinkedIn URL.

insert_chart

Stats Dashboard

Track total jobs, leads scraped, leads with emails, and imported counts.

extension

Custom Actors

Use any Apify actor by providing actor ID and custom JSON input.

Available Scrapers

The following scraper types are available out of the box. You can also use any custom Apify actor.

Scraper	Input	Output	Apify Actor
language Website Contacts	URL	Emails, phones, social links	apify/contact-info-scraper
map Google Maps	Keyword + Location	Business name, email, phone, address, website	compass/crawler-google-places
work LinkedIn Profiles	Profile URL	Name, title, company, skills	anchor/linkedin-profile-scraper
person_search LinkedIn Search	Keyword + Location	Name, title, company, profile URL	anchor/linkedin-search-scraper
menu_book Yellow Pages	Keyword + Location	Business name, phone, address, website	apify/yellow-pages-scraper
photo_camera Instagram	Profile URL	Bio, contact info, follower count	apify/instagram-profile-scraper
tag Twitter / X	Profile URL	Bio, links, contact info	apify/twitter-scraper
extension Custom Actor	Actor ID + JSON input	Varies by actor	any Apify actor

Lead Scraper API JWT

All endpoints require JWT authentication. Base: /api/apify

Settings

GET/api/apify/settings

Get your Apify settings (token, default actor, auto-import)

POST/api/apify/settings

Save settings. Body: apify_token, default_actor, auto_import

Scraping

GET/api/apify/actors

List all available scraper types with their fields and Apify actor IDs

POST/api/apify/scrape

Start a new scrape job

Body	Required	Description
actor_type	✓	Scraper type: `website-contacts`, `google-maps`, `linkedin-profiles`, `linkedin-search`, `yellow-pages`, `instagram`, `twitter`, `custom`
source		URL for URL-based scrapers
keyword		Search keyword for keyword-based scrapers
location		Location filter (e.g. "New York, USA")
max_results		Max results to scrape (default: 50)
list_id		Import leads to existing subscriber list ID
create_list_name		Create new list with this name and import there
custom_actor_id		For `custom` type: Apify actor ID (e.g. `user/my-actor`)
custom_input		For `custom` type: JSON input string

// Example:
                                Scrape a website for contacts
                            POST /api/apify/scrape
                            { "actor_type": "website-contacts",
                            "source": "https://example.com",
                            "max_results": 100,
                            "create_list_name": "Example.com Leads" }

                            Response:
                            { "success": true, "jobId": "uuid", "targetListId": "uuid" }

                            // Example: Scrape Google Maps
                            POST /api/apify/scrape
                            { "actor_type": "google-maps",
                            "keyword": "web design agencies",
                            "location": "New York",
                            "max_results": 50,
                            "create_list_name": "NYC Web Agencies" }
                        

Job Management

GET/api/apify/jobs

List all scrape jobs with status, lead counts, and list names

GET/api/apify/jobs/:id

Get job details + all leads found by this job

POST/api/apify/jobs/:id/refresh

Check Apify for updated run status (for running jobs)

DELETE/api/apify/jobs/:id

Delete a scrape job and all its associated leads

Leads

GET/api/apify/leads

List all scraped leads (across all jobs)

Query Param	Description
search	Search in email, name, company
job_id	Filter by job ID
has_email	Set `1` to only show leads with email
limit	Max results (default: 100)
offset	Pagination offset

DELETE/api/apify/leads/:id

Delete a single lead

Import & Campaigns

POST/api/apify/import

Import leads into a subscriber list

Body	Description
job_id	Import all leads from this job
lead_ids	Array of specific lead IDs to import
list_id	Target subscriber list ID
create_list_name	Create new list with this name
filter_has_email	Only import leads with email addresses

Response:
                            { "success": true, "imported": 47, "skipped": 3,
                            "totalInList": 47, "listId": "uuid" }

POST/api/apify/quick-campaign

Create a campaign directly from scraped leads

Body	Required	Description
job_id		Source job for leads
campaign_name	✓	Campaign name
subject	✓	Email subject line
body_html		Email HTML body — supports merge tags: `{{first_name}}`, `{{last_name}}`, `{{company}}`, `{{email}}`

Stats & Export

GET/api/apify/stats

Dashboard stats: total jobs, total leads, leads with email, imported jobs, recent jobs

GET/api/apify/export

Download leads as CSV file

Query	Description
job_id	Export leads from a specific job only
has_email	Set `1` to export only leads with emails

Lead Scraper Workflow

Complete pipeline from scraping to sending email campaigns:

1

Configure Apify Token

Lead Scraper → Settings → Paste API token → Save

arrow_forward

2

Start a Scrape Job

New Scrape → Pick type → Enter URL/keyword → Choose target list → Start

arrow_forward

3

Leads Extracted & Imported

Apify scrapes the target → Leads (email, name, company, phone) saved → Auto-imported to subscriber list

arrow_forward

4

Create Email Campaign

Quick Campaign from leads → Write email with {{merge_tags}} → Campaign created as draft → Send via Marketing page

Merge Tags for Campaigns

When creating campaigns from scraped leads, use these merge tags in your email body for personalization:

Tag	Replaced With	Example
{{first_name}}	Lead's first name	John
{{last_name}}	Lead's last name	Doe
{{company}}	Company name	Acme Inc
{{email}}	Lead's email address	john@acme.com

// Example
                            campaign email body:
                        Hi {{first_name}},

                        I noticed {{company}} might benefit from our services.
                        Would you be open to a quick 15-minute call this week?

                        Best regards,
                        Your Name

tips_and_updates Pro Tips

• Google Maps is the best scraper for local businesses — try "restaurants", "plumbers", "web agencies" + city name
• Enable Auto-Import in settings to skip the manual import step — leads go straight to your list
• Use Quick Campaign on completed jobs to create a draft campaign in one click
• Export leads as CSV to use in other tools (Mailchimp, HubSpot, etc.)
• The Custom Actor option lets you use any of the 2,000+ scrapers on the Apify marketplace
• Leads are deduplicated by email when importing — no duplicate subscribers

Keyboard Shortcuts

Key	Action
c	Compose new email
r	Reply to email
j / k	Navigate down / up in email list
Enter	Open selected email
e	Archive email
#	Delete email
s	Star / unstar email
/	Focus search
Esc	Close compose / go back
?	Show shortcuts help

Theme Toggle

Eclatrecon AI Mail supports Dark and Light themes. Toggle via Settings → Appearance or the theme button in the header. Your preference is saved per-account and synced via the API.

Security Features

Two-Factor Authentication (2FA)

TOTP-based 2FA via authenticator apps. Enable in Settings → Security.

Login History

Track all login attempts with IP address, device, and timestamp. GET /api/login-history

Session Management

View and revoke active sessions. Admin can revoke any user's sessions.

API Key Permissions

Granular permissions: read, write, send, full. Keys can have expiration dates.

Webhook Signatures

HMAC-SHA256 signatures on all webhook deliveries for authenticity verification.