Mail Panda
Getting StartedAuthenticationContactsTemplatesEmailsCampaignsSegmentsA/B TestsAnalyticsAI FeaturesAPI KeysWebhooksMCP ServerPreferencesDeploymentAPI Reference

Getting Started

Authentication

Login, signup, sessions, and API keys

Overview

The Mail Panda platform uses email and password authentication. Sessions are stored in an admin_token HTTP-only cookie that persists for 7 days. All dashboard routes are protected and require a valid session.

Authentication works differently depending on your deployment mode:

  • Self-hosted — A default admin account (admin@mailpanda.io / password123) is seeded on first launch. Change the password immediately. See db/seed.ts for the seed logic.
  • SaaS — No default account is created. Users register through the /signup page. The seed is skipped when STRIPE_SECRET_KEY is set.

For programmatic access (scripts, integrations, CI/CD), use API keys instead of session cookies. See the API Key Auth section below.

Sign Up

Create a new user account. The response sets a session cookie automatically, so the user is signed in immediately after registration.

POST/api/auth

Create a new account and start a session.

Parameters

NameTypeDescription
action*stringMust be "signup"
email*stringValid email address
password*stringMinimum 6 characters

Request

json
{
  "action": "signup",
  "email": "user@example.com",
  "password": "securepassword"
}

Response

json
{
  "success": true,
  "user": {
    "email": "user@example.com",
    "name": null
  }
}

Sign In

Authenticate with an existing account. On success, an HTTP-only cookie is set with a session token valid for 7 days.

POST/api/auth

Sign in with email and password. Returns user info and sets session cookie.

Parameters

NameTypeDescription
action*stringMust be "login"
email*stringRegistered email address
password*stringAccount password

Request

json
{
  "action": "login",
  "email": "user@example.com",
  "password": "securepassword"
}

Response

json
{
  "success": true,
  "user": {
    "email": "user@example.com",
    "name": "User Name"
  }
}

Check Session

Verify whether the current request has a valid session. Useful for checking authentication status on page load or in middleware.

GET/api/auth

Check if the current session is authenticated. Returns user info if valid.

Response

json
{
  "authenticated": true,
  "user": {
    "email": "user@example.com",
    "name": "User Name"
  }
}

When no valid session exists, the response returns:

json
{
  "authenticated": false,
  "user": null
}

Sign Out

End the current session and clear the authentication cookie.

DELETE/api/auth

Sign out and clear the session cookie.

Response

json
{
  "success": true
}

API Key Auth

For programmatic access to the API (scripts, external integrations, CI/CD pipelines), use API keys instead of session cookies. API keys are managed from the Settings page in the dashboard.

Include the API key in the Authorization header with a Bearer prefix:

bash
curl -H "Authorization: Bearer em_your_api_key_here" \
  http://localhost:3000/api/v1/contacts

API key endpoints are served under the /api/v1/ prefix. See the API Keys documentation for details on creating and managing keys.

Getting StartedContacts