API v1 • Production Ready

API
Reference

Complete REST API for managing users, messages, accounts, and domain configuration. Built for developers who need programmatic access to their email infrastructure.

Quick Start

1. Get API Key

Generate an API key from your dashboard. Keys are scoped to a single domain.

Create Key

2. Authenticate

Include your API key in the Authorization header of every request.

3. Make Requests

Start building with our RESTful API. All responses are JSON.

authentication.sh

curl 'https://api.inmail.dev/v1/users' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Base URL

Production

https://api.inmail.dev/v1

Endpoints

Users

Manage users within your domain. Create, list, update, and delete users programmatically.

GET/v1/users

List all users for your domain

Parameters

limit•integer•Number of results (max 100, default 50)

cursor•string•Pagination cursor from previous response

Example

curl 'https://api.inmail.dev/v1/users?limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/users

Create a new user

Request Body

{
  "email": "[email protected]",
  "password": "securepassword",
  "name": "John Doe"
}

Example

curl -X POST 'https://api.inmail.dev/v1/users' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "password": "securepassword",
    "name": "John Doe"
  }'

GET/v1/users/:email

Get a specific user by email

Example

curl 'https://api.inmail.dev/v1/users/[email protected]' \
  -H 'Authorization: Bearer YOUR_API_KEY'

PUT/v1/users/:email

Update a user

Request Body

{
  "name": "Jane Doe",
  "password": "newpassword"
}

Example

curl -X PUT 'https://api.inmail.dev/v1/users/[email protected]' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Jane Doe"}'

DELETE/v1/users/:email

Deactivate a user

Example

curl -X DELETE 'https://api.inmail.dev/v1/users/[email protected]' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Messages

Access and manage messages for your domain. List, retrieve, and delete messages with cursor-based pagination.

GET/v1/messages

List messages for your domain

Parameters

limit•integer•Number of results (max 100, default 50)

cursor•string•Pagination cursor

account•string•Filter by account email

Example

curl 'https://api.inmail.dev/v1/messages?limit=20&[email protected]' \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/messages/:id

Get a specific message with signed download URL

Example

curl 'https://api.inmail.dev/v1/messages/msg_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

DELETE/v1/messages/:idComing Soon

Delete a message (Not yet implemented)

Example

curl -X DELETE 'https://api.inmail.dev/v1/messages/msg_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/messages/:id/downloadComing Soon

Download message content with signed token

Parameters

token•string•Signed download token from message response

Example

curl 'https://api.inmail.dev/v1/messages/msg_abc123/download?token=SIGNED_TOKEN' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Accounts

Manage email accounts for your domain. Create catch-all or specific email addresses.

GET/v1/accounts

List all accounts for your domain

Parameters

limit•integer•Number of results (max 100, default 50)

cursor•string•Pagination cursor

Example

curl 'https://api.inmail.dev/v1/accounts' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/accounts

Create a new account

Request Body

{
  "email": "[email protected]"
}

Example

curl -X POST 'https://api.inmail.dev/v1/accounts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]"}'

GET/v1/accounts/:id

Get a specific account

Example

curl 'https://api.inmail.dev/v1/accounts/acc_123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

PUT/v1/accounts/:id

Update an account

Request Body

{
  "email": "[email protected]"
}

Example

curl -X PUT 'https://api.inmail.dev/v1/accounts/acc_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]"}'

DELETE/v1/accounts/:id

Delete an account

Example

curl -X DELETE 'https://api.inmail.dev/v1/accounts/acc_123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Configuration

Manage domain configuration settings like catch-all and attachment handling.

GET/v1/config

Get domain configuration

Example

curl 'https://api.inmail.dev/v1/config' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/config

Create domain configuration

Request Body

{
  "attachments": true,
  "catch_all": false
}

Example

curl -X POST 'https://api.inmail.dev/v1/config' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "attachments": true,
    "catch_all": false
  }'

PUT/v1/config

Update domain configuration

Request Body

{
  "attachments": false
}

Example

curl -X PUT 'https://api.inmail.dev/v1/config' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"attachments": false}'

Statistics

Get domain statistics and metrics.

GET/v1/statsBeta

Get domain statistics

Parameters

days•integer•Number of days to include (default 7)

Example

curl 'https://api.inmail.dev/v1/stats?days=30' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Send Email

Send outbound emails from your domain. Supports HTML and plain text content with CC recipients If no custom domain is configured, your messages will be delivered from a @inmail.dev address.

POST/v1/send

Send an email from your domain

Request Body

{
  "from": "[email protected]",
  "to": [
    "[email protected]"
  ],
  "cc": [
    "[email protected]"
  ],
  "subject": "Hello from InMail",
  "textBody": "Plain text message",
  "htmlBody": "<h1>HTML message</h1>",
  "charset": "UTF-8"
}

Example

curl -X POST 'https://api.inmail.dev/v1/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Hello from InMail",
    "textBody": "This is the plain text version",
    "htmlBody": "<h1>Hello!</h1><p>This is the HTML version.</p>",
    "charset": "UTF-8"
  }'

Send Logs

View logs of all emails sent through the /send endpoint. Track delivery status, errors, and message metadata for your domain.

GET/v1/send-logs

List all send logs for your domain with pagination

Example

curl 'https://api.inmail.dev/v1/send-logs?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/send-logs/{id}

Get detailed information about a specific send log entry

Example

curl 'https://api.inmail.dev/v1/send-logs/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Webhooks

Configure webhooks to receive real-time notifications when emails arrive at your domain. When an email is received, we'll send a POST request to your configured endpoint with the email details.

Request Method

POST

Expected Response

200 OK

Timeout

10 seconds

Retry Policy: If your webhook endpoint returns a non-200 status or times out, we'll retry with exponential backoff.

Security: Configure an Authorization header value in your domain settings for additional security. Your webhook endpoint can verify this header to ensure requests are from InMail.

webhook-payload.json

{
  "message_id": "J045OvxQ71A3CwMLYlMSDxAjsEx",
  "sender": "[email protected]",
  "recipients": [ 
    "[email protected]",
    "[email protected]"
  ],
  "subject": "Hello from InMail",
  "text_body": "plain text",
  "html_body": "<html>",
  "headers": {
    "Arc-Authentication-Results": [ 
      "i=2; mx.google.com; dkim=pass [email protected] header.s=default header.b=BxqDCS93; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=inmail.dev"
    ],
    "Arc-Message-Signature": [ 
      "i=2; a=rsa-sha256; darn=newsletterss.com",
      "i=1; a=rsa-sha256; OA3b9OOXSwGkiEtdy6Zh/nkORY67lOH77AOtWKaMreX/IcccgViELz f6tA==; dara=google.com"
    ],
    "Arc-Seal": [ 
      "i=2; a=rsa-sha256; t=1777292122; cv=pass; d=google.com; s=arc-20240605;"
    ],
    "Authentication-Results": [ 
      "mx.google.com; dkim=pass [email protected] header.s=default header.b=BxqDCS93; dkim=pass [email protected] header.s=s2604271415 header.b=he9qAdJR;"
    ],
    "Content-Type": [ 
      "multipart/alternative; boundary=451bff2efa7284c1672df9b346794b012004871cc60c257d8d525125d39e"
    ],
    "Date": [ 
      "Mon, 27 Apr 2026 12:15:03 +0000"
    ],
    "Delivered-To": [ 
      "[email protected]",
      "[email protected]"
    ],
    "Dkim-Signature": [ 
      "v=1; a=rsa-sha256; c=simple/simple; d=fwd.privateemail.com; s=default; t=1777292118; "
    ],
    "From": [ 
      ""Postmaster" <[email protected]>"
    ],
    "List-Unsubscribe": [ 
      "<https://example.com/unsubscribe/dNQwPm-Q68xxpl-4oVxEw>"
    ],
    "List-Unsubscribe-Post": [ 
      "List-Unsubscribe=One-Click"
    ],
    "Message-Id": [ 
      "<[email protected]>"
    ],
    "Mime-Version": [ 
      "1.0"
    ],
    "Received": [ 
      "by mail-yx1-f43.google.com with SMTP id 956f58d0204a3-656d749109cso1335883d50.3 for <[email protected]>; Mon, 27 Apr 2026 05:15:22 -0700 (PDT)"
    ],
    "Received-Spf": [ 
      "pass (google.com: domain of srs0=eloa=c2=1=bhujde34ok68jvo055o0qooimhb03nnq@fwd-03.fwd.privateemail.com designates 184.45.22.18 as permitted sender) client-ip=1184.45.22.18;"
    ],
    "Resent-Date": [ 
      "Mon, 27 Apr 2026 08:15:16 -0400 (EDT)"
    ],
    "Resent-From": [ 
      "[email protected]"
    ],
    "Resent-Message-Id": [ 
      "<[email protected]>"
    ],
    "Return-Path": [ 
      "<SRS0=eLOA=C2=1=BHUJDE34OK68JVO055O0QOOIMHB03NNQ@fwd-03.fwd.inmail.dev>"
    ],
    "Subject": [ 
      "Hello InMail"
    ],
    "To": [ 
      "<[email protected]>"
    ],
    "X-Auto-Response-Suppress": [ 
      "All"
    ],
    "X-Forwarded-Encrypted": [ 
      "i=2;[email protected]",
      "i=2;[email protected]"
    ],
    "X-Forwarded-For": [ 
      "[email protected] [email protected]"
    ],
    "X-Forwarded-To": [ 
      "[email protected]"
    ],
    "X-Gm-Message-State": [ 
      "AOJu0Y"
    ],
    "X-Google-Dkim-Signature": [ 
      "v=1; a=rsa-sha256;"
    ],
    "X-Jellyfish-No-Auto-Response": [ 
      "1"
    ],
    "X-Original-To": [ 
      "<[email protected]>"
    ],
    "X-Received": [ 
      "by 2002:a53:d00a:0:b0:64f:fc0d:624b with SMTP id 1777292121333; Mon, 27 Apr 2026 05:15:21 -0700 (PDT)"
    ],
    "X-Rspamd-Queue-Id": [ 
      "4g42ZX4YYSz67Dk"
    ],
    "X-Sender-Id": [ 
      "dNQwPm-Q68xxpl-4oVxEw"
    ],
    "X-Sieve-Redirected-From": [ 
      "[email protected]"
    ],
    "X-Virus-Scanned": [ 
      "ClamAV using ClamSMTP"
    ]
  }},
  "attachments": null,
  "received_at": "2026-04-27T12:15:22.995034956Z",
  "domain": "newsletterss.com",
  "account": "mauricio"
}

Response Format

Success Response

{
  "data": [...],
  "pagination": {
    "next_cursor": "abc123",
    "has_more": true,
    "limit": 50
  }
}

Error Response

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "status": 401
  }
}

Rate Limits

1,000

Requests per minute

100,000

Requests per day

100

Max results per page

Security Best Practices

Never Expose API Keys

API keys are shown only once during creation. Store them securely and never commit them to version control or expose them in client-side code.

Rotate Keys Regularly

Create new API keys periodically and deactivate old ones. Each key is scoped to a single domain for security.

Use Environment Variables

Store API keys in environment variables or secure secret management systems. Never hardcode them in your application.

Monitor Usage

Track when your API keys were last used in the dashboard. Deactivate any keys that show suspicious activity.

CLI

The InMail CLI is an open-source command-line tool for managing your email infrastructure. It works for both humans and AI agents, with full support for non-interactive mode, JSON output, and a built-in REPL.

Install

terminal

curl -fsSL https://raw.githubusercontent.com/inmaildev/inmail-cli/main/install.sh | bash

Or install from source: go install github.com/inmaildev/inmail-cli@latest

Authenticate

Interactive

inmail configure

Environment variable

export INMAIL_API_KEY=your_key_here

Commands

inmail messages list --limit 10

List the last 10 messages

inmail messages list --account [email protected]

Filter by account

inmail users create --email [email protected] --name "Alice"

Create a user

inmail send --to [email protected] --subject "Hi" --text "Hello"

Send an email

inmail stats --days 30

30-day statistics

inmail config get

Get domain configuration

Agent-Friendly Usage

The CLI is designed for AI agent and CI environments. Use --non-interactive to skip all confirmation prompts, and --output json for machine-parseable output.

agent-example.sh

# Non-interactive JSON output for agents
inmail messages list --output json --non-interactive

# Pipe commands to the REPL for batch execution
printf 'messages list\nstats --days 7\n' | inmail repl --non-interactive --output json

# Configure via env var (no prompts)
INMAIL_API_KEY=${SECRET} inmail users list --non-interactive --output json

Interactive REPL

The inmail repl command starts an interactive session with command history and readline editing. Session context is maintained and trimmed automatically at ~4,000 tokens.

repl session

$ inmail repl
InMail REPL — type 'help' for commands, 'exit' to quit

inmail › messages list --limit 3
{ "data": [...], "pagination": { "has_more": true } }

inmail › users get [email protected]
{ "email": "[email protected]", "name": "Alice" }

inmail › exit
→ Goodbye

Ready to Build?

Generate your first API key and start integrating with your email infrastructure in minutes.

Get Your API Key

API Reference

Quick Start

1. Get API Key

2. Authenticate

3. Make Requests

Base URL

Endpoints

Users

Messages

Accounts

Configuration

Statistics

Send Email

Send Logs

Webhooks

Response Format

Rate Limits

Security Best Practices

Never Expose API Keys

Rotate Keys Regularly

Use Environment Variables

Monitor Usage

CLI

Install

Authenticate

Commands

Agent-Friendly Usage

Interactive REPL

Ready to Build?

API
Reference