Email Management API

A comprehensive RESTful API for managing your email infrastructure - domains, mailboxes, aliases, and sync jobs.

Authentication

Authentication is required for all API requests. Provide your API credentials in the Authorization header.
```
Authorization: Bearer YOUR_API_KEY
```

Base URL

All API requests should be made to this base URL:
```
https://your-email-server.example.com/api/v1
```

Domains Endpoints

Endpoints for managing email domains.

Endpoint	Method	Description
/api/v1/domains	GET	Retrieve a list of all domains in your system
/api/v1/domains	POST	Add a new domain to your system
/api/v1/domains/{domain}	PUT	Update an existing domain
/api/v1/domains/{domain}	DELETE	Delete a domain from your system

Domain Parameters

Parameters used when creating or updating domains.

Parameter	Type	Required	Description
domain	string	Yes	Domain name (e.g., example.com)
active	boolean	Yes	Whether the domain is active
aliases	integer	Yes	Maximum number of aliases for this domain
backupmx	boolean	No	Whether this domain is a backup MX
defquota	integer	Yes	Default quota for mailboxes in MB
description	string	No	Description of this domain
mailboxes	integer	Yes	Maximum number of mailboxes for this domain
maxquota	integer	Yes	Maximum quota for mailboxes in MB
quota	integer	Yes	Total quota for this domain in MB

Mailboxes Endpoints

Endpoints for managing email mailboxes.

Endpoint	Method	Description
/api/v1/mailboxes	GET	Retrieve a list of all mailboxes in your system
/api/v1/mailboxes/{email}	GET	Retrieve details for a specific mailbox
/api/v1/mailboxes	POST	Add a new mailbox to your system
/api/v1/mailboxes/{email}	PUT	Update an existing mailbox
/api/v1/mailboxes/{email}	DELETE	Delete a mailbox from your system

Mailbox Parameters

Parameters used when creating or updating mailboxes.

Parameter	Type	Required	Description
active	boolean	Yes	Whether the mailbox is active
domain	string	Yes (create only)	Domain for this mailbox
local_part	string	Yes (create only)	Local part of the email address (before @)
name	string	Yes	Display name for this mailbox
password	string	Yes (create only)	Password for this mailbox
quota	integer	Yes	Quota for this mailbox in MB
force_pw_update	boolean	No	Force password update on next login
tls_enforce_in	boolean	No	Enforce TLS for incoming connections
tls_enforce_out	boolean	No	Enforce TLS for outgoing connections

Aliases Endpoints

Endpoints for managing email aliases.

Endpoint	Method	Description
/api/v1/aliases	GET	Retrieve a list of all aliases in your system
/api/v1/aliases	POST	Add a new alias to your system
/api/v1/aliases/{id}	PUT	Update an existing alias
/api/v1/aliases/{id}	DELETE	Delete an alias from your system

Error Handling

The API uses standard HTTP status codes and returns error messages in a consistent format.

{
  "type": "error",
  "msg": "Error description"
}

HTTP Code	Description	Example Message
400	Bad Request	Invalid parameters
401	Unauthorized	Invalid credentials
404	Not Found	Resource doesn't exist
409	Conflict	Resource already exists
500	Internal Server Error	Server encountered an error

Rate Limiting

The API has rate limiting to prevent abuse. If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Rate Limit Header	Description	Example Value
X-RateLimit-Limit	Maximum requests allowed per period	100
X-RateLimit-Remaining	Remaining requests in current period	45
X-RateLimit-Reset	Time until limit resets (Unix timestamp)	1644231658

Example Requests

Here are some example API requests and responses.

Create a new domain

POST /api/v1/domains
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "domain": "example.com",
  "active": true,
  "aliases": 400,
  "backupmx": false,
  "defquota": 3072,
  "description": "Example domain",
  "mailboxes": 10,
  "maxquota": 10240,
  "quota": 10240
}

Response

{
  "type": "success",
  "msg": "Domain has been added to system"
}

Create a new mailbox

POST /api/v1/mailboxes
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "active": true,
  "domain": "example.com",
  "local_part": "user",
  "name": "Example User",
  "password": "securepassword123",
  "quota": 3072,
  "force_pw_update": false,
  "tls_enforce_in": false,
  "tls_enforce_out": false
}

Response

{
  "type": "success",
  "msg": "Mailbox has been added"
}