API Reference

Base URL: https://api.ivymail.io

All requests require an x-api-key header. All request and response bodies are JSON. Every response follows the envelope format:

JSON

{
  "success": true | false,
  "data": { ... },
  "error": "message (only on failure)"
}

Send Email

Code

POST /v1/send

Send a transactional email to one or more recipients.

Request body

Field	Type	Required	Description
`to`	`string[]`	Yes	Recipient addresses (max 50)
`from_email`	`string`	Yes	Sender, e.g. `"Name <you@domain.com>"`
`subject`	`string`	Yes	Subject line
`html`	`string`	No	HTML body
`text`	`string`	No	Plain text body
`reply_to`	`string`	No	Reply-to address

At least one of html or text is required.

Response

JSON

{
  "success": true,
  "data": {
    "message_id": "abc123-def456",
    "status": "sent"
  }
}

Get Send Logs

Code

GET /v1/send/logs

Retrieve send logs for your workspace.

Query parameters

Parameter	Type	Default	Description
`limit`	`number`	50	Max results (1–100)
`offset`	`number`	0	Pagination offset
`type`	`string`	-	Filter by log type: `send`, `bounce`, `complaint`
`status`	`string`	-	Filter by status: `sent`, `delivered`, `bounced`, `complained`, `suppressed`, `failed`

Response

JSON

{
  "success": true,
  "data": [
    {
      "id": "log_xxxx",
      "type": "send",
      "status": "delivered",
      "to": "user@example.com",
      "from_email": "you@yourdomain.com",
      "subject": "Hello",
      "message_id": "abc123",
      "created_at": "2026-02-25T12:00:00Z"
    }
  ]
}

Get Send Stats

Code

GET /v1/send/stats

Retrieve aggregated sending statistics for your workspace.

Response

JSON

{
  "success": true,
  "data": {
    "total_sent": 1250,
    "delivered": 1200,
    "bounced": 30,
    "complained": 5,
    "suppressed": 10,
    "failed": 5
  }
}

List Domains

Code

GET /v1/domains

List all domains in your workspace.

Response

JSON

{
  "success": true,
  "data": [
    {
      "id": "dom_xxxx",
      "domain": "mail.yourapp.com",
      "status": "verified",
      "created_at": "2026-02-20T10:00:00Z"
    }
  ]
}

Add Domain

Code

POST /v1/domains

Request body

Field	Type	Required	Description
`domain`	`string`	Yes	Domain to add

Response

Returns the domain object with DNS records to configure.

Verify Domain

Code

POST /v1/domains/{id}/verify

Trigger DNS verification for a domain.

Response

JSON

{
  "success": true,
  "data": {
    "id": "dom_xxxx",
    "domain": "mail.yourapp.com",
    "status": "verified"
  }
}

List API Keys

Code

GET /v1/api-keys

List all API keys in your workspace. Key values are masked.

Create API Key

Code

POST /v1/api-keys

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Human-readable name

Response

Returns the full API key value (shown only once).

Health Check

Code

GET /v1/health/check

No authentication required. Returns 200 with:

JSON

{
  "status": "ok"
}

For AI agents & LLMs

If you're an AI agent, here are the most common operations:

Send an email:

Bash

curl -X POST https://api.ivymail.io/v1/send \
  -H "x-api-key: $IVYMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from_email":"Name <you@domain.com>","to":["user@example.com"],"subject":"Hello","text":"Body"}'

Check logs:

Bash

curl "https://api.ivymail.io/v1/send/logs?limit=10" -H "x-api-key: $IVYMAIL_API_KEY"

Check stats:

Bash

curl https://api.ivymail.io/v1/send/stats -H "x-api-key: $IVYMAIL_API_KEY"

List domains:

Bash

curl https://api.ivymail.io/v1/domains -H "x-api-key: $IVYMAIL_API_KEY"

Add a domain:

Bash

curl -X POST https://api.ivymail.io/v1/domains \
  -H "x-api-key: $IVYMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.yourapp.com"}'

Download the full skills file for a self-contained reference.