MailDoor — Secure Email Gateway

Quick Start

MailDoor lets you send emails from your Gmail account via a simple REST API. You authenticate with an API key, and emails are delivered through Gmail SMTP using your App Password.

Sign in with Google and set up your Gmail App Password on the API Keys page.
Create an API key from the dashboard.
Use the API key in the x-api-key header of your requests.

Authentication

All API requests require an API key passed in the x-api-key header. API keys can be created and managed from the API Keys page.

Header format

x-api-key: your_api_key_here

API keys are hashed (SHA-256) before storage. You will only see the full key once — when you create it.

Send Email

POST/api/email/send

Send an email from your Gmail account. Requires a valid App Password to be configured.

Request Body (JSON)

Field	Type	Required	Description
to	string	Yes	Recipient email address
subject	string	Yes	Email subject (1–998 chars)
body	string	Yes	Email body text or HTML (max 50,000 chars)
fromName	string	No	Display name for the sender (max 120 chars)
contentType	string	No	"text" (default) or "html"

Request

curl -X POST https://your-domain.com/api/email/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from MailDoor",
    "body": "This is a test email sent via MailDoor API."
  }'

Response (200)

{
  "status": "success",
  "message": "Email sent successfully",
  "data": {
    "messageId": "<abc123@smtp.gmail.com>",
    "accepted": ["recipient@example.com"],
    "rejected": [],
    "from": "you@gmail.com",
    "to": "recipient@example.com",
    "subject": "Hello from MailDoor",
    "status": "SENT",
    "sentAt": "2025-01-15T12:00:00.000Z"
  }
}

Rate Limiting

Each API key is rate-limited to prevent abuse. When you exceed the limit, the API returns a 429 status code.

Rate limit exceeded (429)

{
  "status": "error",
  "message": "Rate limit exceeded for this API key. Try again later.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Error Responses

All errors follow a consistent format. The code field helps you handle errors programmatically.

400Validation Error

{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    { "field": "to", "message": "A valid recipient email address is required" }
  ]
}

401Invalid or Missing API Key

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

403API Key Revoked

{
  "status": "error",
  "message": "API key has been revoked",
  "code": "API_KEY_REVOKED"
}

400No App Password Configured

{
  "status": "error",
  "message": "App password not configured. Please set your Gmail App Password first.",
  "code": "APP_PASSWORD_REQUIRED"
}

401Gmail Authentication Failed

{
  "status": "error",
  "message": "Gmail authentication failed. Your App Password may be invalid or revoked.",
  "code": "GMAIL_AUTH_FAILED"
}

422Email Rejected by Gmail

{
  "status": "error",
  "message": "Email rejected: recipient address does not exist or mailbox is full.",
  "code": "EMAIL_REJECTED"
}

503Gmail Temporarily Unavailable

{
  "status": "error",
  "message": "Gmail is temporarily unavailable. Please try again in a few minutes.",
  "code": "GMAIL_UNAVAILABLE"
}