Manage account settings — IP pools, email signatures, SMTP pools, unsubscribe pages, and whitelabel configuration

The settings API covers account-level configuration. All endpoints require an active dashboard session.

Requires active session (dashboard only).

Get audit log

GET/api/settings/audit

Retrieve the compliance audit log. Records include consent events, domain verification results, and billing actions.

Query parameters

pageintegerquerydefault: 1

Page number.

limitintegerquerydefault: 50

Records per page (max 100).

event_typestringquery

Filter by event type (e.g. consent_granted, domain_verified).

Response fields

entriesArray<object>

Audit log entries, each with id, action, timestamp, and metadata.

paginationobject

Pagination metadata: page, limit, and total.

{
  "entries": [
    {
      "id": "audit_01hx9k",
      "action": "consent_granted",
      "timestamp": "2025-06-14T09:00:00Z",
      "metadata": { "analytics": true, "marketing": true }
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 214 }
}

List IP pools

GET/api/settings/ip-pools

List all IP pools with current capacity.

Response fields

[]Array<object>

IP pools, each with id, name, pool_type, ips, and capacity.

[
  { "id": "pool_t01", "name": "transactional", "pool_type": "transactional", "ips": ["198.51.100.42"], "capacity": 50000 }
]

Create IP pool

POST/api/settings/ip-pools

Create a custom IP pool.

Request body

namestringbody

Display name for the pool.

ipsstring[]body

IP addresses in the pool.

pool_typestringbody

Pool type, e.g. transactional.

{
  "name": "my-transactional-pool",
  "ips": ["198.51.100.42", "198.51.100.43"],
  "pool_type": "transactional"
}

List signatures

GET/api/settings/signatures

List all saved email signatures.

Response fields

[]Array<object>

Signatures, each with id, name, html, and is_default.

[
  { "id": "sig_abc1", "name": "Default Signature", "html": "<p>Best, Jane</p>", "is_default": true }
]

Create signature

POST/api/settings/signatures

Create a new signature.

Request body

namestringbodyrequired

Display name for the signature.

htmlstringbodyrequired

HTML content of the signature.

is_defaultbooleanbody

Set as the default signature. Unsets any existing default.

curl -X POST /api/settings/signatures \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Signature",
    "html": "<p>Thanks,<br><strong>Jane Doe</strong><br>Sales · example.com</p>",
    "is_default": false
  }'

Delete signature

DELETE/api/settings/signatures

Delete a signature by ID. If the deleted signature was the default, no signature becomes default — you must explicitly set a new one.

Query parameters

idstringqueryrequired

ID of the signature to delete.

DELETE /api/settings/signatures?id=sig_abc1

List SMTP pools

GET/api/settings/smtp-pools

List SMTP pool configurations. Passwords are never returned.

GET /api/settings/smtp-pools

Create SMTP pool

POST/api/settings/smtp-pools

Create an SMTP pool.

Request body

namestringbody

Display name.

hoststringbody

SMTP server hostname.

portintegerbody

SMTP port (typically 587 or 465).

usernamestringbody

SMTP username.

passwordstringbody

SMTP password (stored encrypted, never returned).

encryptiontls | ssl | nonebody

Connection encryption.

POST /api/settings/smtp-pools
Content-Type: application/json

Test SMTP pool

POST/api/settings/smtp-pools/:id/test

Test an SMTP connection. No body needed.

Path parameters

idstringpathrequired

ID of the SMTP pool to test.

Response fields

successboolean

true when the connection succeeded.

latencyMsnumber

Connection latency in milliseconds.

errorstring

Error message when the connection failed.

POST /api/settings/smtp-pools/:id/test

For the dedicated SMTP Pools public API surface, see the SMTP Pools reference page.

Get unsubscribe page

GET/api/settings/unsubscribe-page

Get the current unsubscribe page configuration.

Response fields

typestring

default, custom_url, or template.

urlstring | null

The custom unsubscribe URL, when configured.

templateIdstring | null

The template ID, when configured.

{ "type": "default", "url": null, "templateId": null }

Update unsubscribe page

POST/api/settings/unsubscribe-page

Configure a custom unsubscribe experience.

Request body

typedefault | custom_url | templatebody

default uses MisarMail's built-in page.

urlstringbody

Required when type is custom_url.

templateIdstringbody

Required when type is template.

{ "type": "custom_url", "url": "https://app.example.com/unsubscribe" }

Get whitelabel config

Whitelabel configuration requires the Max plan.

GET/api/settings/whitelabel

Get the current whitelabel configuration.

Response fields

brandNamestring

Brand name shown in the UI.

logoUrlstring

URL to your logo.

primaryColorstring

Hex colour for buttons and accents.

customDomainstring

Custom sending domain shown in footers.

hideFooterBrandingboolean

Whether the "Powered by MisarMail" footer is hidden.

{
  "brandName": "Acme Mail",
  "logoUrl": "https://cdn.example.com/logo.png",
  "primaryColor": "#22c55e",
  "customDomain": "mail.example.com",
  "hideFooterBranding": true
}

Update whitelabel config

POST/api/settings/whitelabel

Update whitelabel settings. All fields are optional — only provided fields are updated.

Request body

brandNamestringbody

Replaces "MisarMail" in the UI.

logoUrlstringbody

URL to your logo (PNG/SVG, max 500 KB).

primaryColorstringbody

Hex colour for buttons and accents.

customDomainstringbody

Custom sending domain shown in footers.

hideFooterBrandingbooleanbody

Remove "Powered by MisarMail" footer.

{ "brandName": "Acme Mail", "hideFooterBranding": true }

Settings

Get audit log

List IP pools

Create IP pool

List signatures

Create signature

Delete signature

List SMTP pools

Create SMTP pool

Test SMTP pool

Get unsubscribe page

Update unsubscribe page

Get whitelabel config

Update whitelabel config