openapi: 3.1.0
info:
  title: MailerLogic API
  version: 1.0.0
  description: |
    Complete REST API for managing email delivery, tracking, and analytics.

    Get started in minutes:
    1. Get your API key from your customer dashboard
    2. Send authenticated requests using the Bearer token
    3. Start sending emails via SMTP or API

    For detailed guides, see the Getting Started section in the navigation.
  contact:
    name: Support
    email: support@mailerlogic.com
    url: https://support.mailerlogic.com
servers:
  - url: https://api.mailerlogic.io
    description: Production API server
  - url: https://eu.api.mailerlogic.io
    description: EU Data Center (Coming Soon)
tags:
  - name: Quickstart Guide
    x-displayName: Quickstart Guide
    description: >
      Get started with MailerLogic in minutes. This guide walks you through
      sending your first email.


      ### Prerequisites


      - Active MailerLogic account

      - Your API key (available in your customer dashboard)

      - A verified sending domain (or use the verification process below)


      ### Step 1: Get Your API Key


      Your API key is available in your customer dashboard. It will look like
      this:


      ```

      ml_live_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

      ```


      **Keep this key secure!** Never commit it to version control or share it
      publicly.


      ### Step 2: Set Up Your Domain


      Add your domain via the API:


      ```bash

      curl -X POST https://api.mailerlogic.io/api/customer/domains \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"domain": "mail.yourdomain.com"}'
      ```


      Get DNS records to add:


      ```bash

      curl https://api.mailerlogic.io/api/customer/domains/{DOMAIN_ID}/dns \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```


      Add the returned DNS records to your DNS provider, then verify:


      ```bash

      curl -X POST
      https://api.mailerlogic.io/api/customer/domains/{DOMAIN_ID}/verify \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```


      ### Step 3: Send Your First Email


      You can send emails via **REST API** or **SMTP**.


      #### Option A: Send via REST API (Recommended)


      ```bash

      curl -X POST https://api.mailerlogic.io/api/send \
        -H "X-API-Key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "from": "hello@mail.yourdomain.com",
          "to": "recipient@example.com",
          "subject": "Hello from MailerLogic!",
          "html": "<h1>Hello!</h1><p>Your first email sent via MailerLogic.</p>",
          "text": "Hello! Your first email sent via MailerLogic."
        }'
      ```


      #### Option B: Send via SMTP


      Get your SMTP credentials:


      ```bash

      curl https://api.mailerlogic.io/api/smtp-credentials \
        -H "X-API-Key: YOUR_API_KEY"
      ```


      **Node.js Example:**


      ```javascript

      const nodemailer = require('nodemailer');


      const transporter = nodemailer.createTransport({
        host: 'smtp.mailerlogic.io',
        port: 587,
        auth: {
          user: 'your-email@example.com',
          pass: 'smtp_password_here'
        }
      });


      const mailOptions = {
        from: 'sender@mail.yourdomain.com',
        to: 'recipient@example.com',
        subject: 'Hello from MailerLogic!',
        html: '<h1>Hello!</h1><p>Your first email sent via MailerLogic.</p>'
      };


      transporter.sendMail(mailOptions, (error, info) => {
        if (error) console.log('Error:', error);
        else console.log('Email sent:', info.messageId);
      });

      ```


      **Python Example:**


      ```python

      import smtplib

      from email.mime.text import MIMEText

      from email.mime.multipart import MIMEMultipart


      msg = MIMEMultipart('alternative')

      msg['Subject'] = 'Hello from MailerLogic!'

      msg['From'] = 'sender@mail.yourdomain.com'

      msg['To'] = 'recipient@example.com'


      html = '<h1>Hello!</h1><p>Your first email sent via MailerLogic.</p>'

      msg.attach(MIMEText(html, 'html'))


      with smtplib.SMTP('smtp.mailerlogic.io', 587) as server:
          server.starttls()
          server.login('your-email@example.com', 'smtp_password_here')
          server.send_message(msg)
      ```


      **PHP Example:**


      ```php

      use PHPMailer\PHPMailer\PHPMailer;


      $mail = new PHPMailer(true);

      $mail->isSMTP();

      $mail->Host = 'smtp.mailerlogic.io';

      $mail->SMTPAuth = true;

      $mail->Username = 'your-email@example.com';

      $mail->Password = 'smtp_password_here';

      $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;

      $mail->Port = 587;


      $mail->setFrom('sender@mail.yourdomain.com');

      $mail->addAddress('recipient@example.com');

      $mail->Subject = 'Hello from MailerLogic!';

      $mail->Body = '<h1>Hello!</h1><p>Your first email sent via
      MailerLogic.</p>';

      $mail->isHTML(true);


      $mail->send();

      ```


      ### Step 4: Enable Tracking


      Tracking is enabled by default on your account. Your emails will
      automatically include:


      - **Open tracking**: A tiny pixel that tracks when emails are opened

      - **Click tracking**: Automatic link wrapping to track clicks

      - **Unsubscribe links**: One-click unsubscribe per RFC 8058


      To disable tracking for specific emails, you can configure it in your
      account settings.


      ### Step 5: Check Your Statistics


      View your email statistics:


      ```bash

      curl https://api.mailerlogic.io/api/customer/usage \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```


      ### Next Steps


      **Test Your Content** - Use our content scoring API before sending
      campaigns:

      ```bash

      curl -X POST https://api.mailerlogic.io/api/content-score \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"subject": "Your Newsletter", "html": "<html>...</html>", "text": "..."}'
      ```


      **Set Up Webhooks** - Receive real-time notifications for bounces and
      complaints:

      ```bash

      curl -X PUT https://api.mailerlogic.io/api/customer/profile \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"webhook_url": "https://your-domain.com/webhooks/mailerlogic"}'
      ```


      **Best Practices**:

      - Always use verified domains

      - Enable tracking for engagement insights

      - Monitor your bounce and complaint rates

      - Use suppression lists to avoid known bad addresses

      - Test content before sending large campaigns


      ### Common Issues


      **"Domain not verified"** - Add all DNS records and wait for propagation
      (up to 48 hours).


      **"SMTP authentication failed"** - Get fresh credentials from
      `/api/smtp-credentials`.


      **"Rate limit exceeded"** - Wait for reset (1000 requests per 15 minutes).


      ---


      **Need Help?** Email support@mailerlogic.com or visit
      https://support.mailerlogic.com
  - name: Features Overview
    x-displayName: Features Overview
    description: >
      MailerLogic provides enterprise-grade email delivery infrastructure with
      powerful APIs, deliverability optimization, and comprehensive analytics.
      Built by developers, for developers.


      ---


      ### 📧 Email Sending


      **REST API**

      - Simple `/api/send` endpoint

      - Send individual emails via HTTP with full tracking

      - Template support with variable substitution

      - Custom headers and metadata

      - Auto-domain selection for convenience


      **SMTP Integration**

      - Industry-standard SMTP server (ports 587, 2525)

      - Automatic connection pooling and retry logic

      - Works with all major email clients and libraries

      - Maximum 50 recipients per email, 10MB including attachments


      **Deliverability First**

      - Built-in automated IP warming schedules (2-4 weeks)

      - Smart throttling by recipient domain

      - Automatic bounce and complaint handling

      - Real-time reputation monitoring across all IPs


      ---


      ### 🌐 Domain Management & Authentication


      **Easy Domain Setup**

      - One-click domain addition via API or dashboard

      - Automatic DKIM key generation (2048-bit RSA)

      - SPF and DMARC record recommendations

      - DNS verification with detailed status reporting


      **Email Authentication**

      - DKIM signing on all outbound emails

      - SPF alignment verification

      - DMARC policy support

      - Custom DKIM selectors available


      **Multi-Domain Support**

      - Manage unlimited verified sending domains

      - Domain-level statistics and reputation tracking

      - Tag-based organization

      - Custom tracking domains for branded links


      ---


      ### 📊 Advanced Tracking & Analytics


      **Open Tracking**

      - Real-time open detection with invisible 1x1 pixel

      - Unique vs. total opens tracking

      - Email client identification (Gmail, Outlook, Apple Mail)

      - Geographic location by IP

      - Device type and OS detection


      **Click Tracking**

      - Automatic link wrapping with sub-100ms redirects

      - Click-through rate analytics

      - Individual link performance metrics

      - Bot detection and filtering


      **Event Timeline**

      - Comprehensive status tracking: queued → sent → delivered → opened →
      clicked

      - Bounce classification (hard vs. soft)

      - Complaint (spam report) tracking

      - Custom event webhooks with retry logic


      **Real-Time Statistics**

      - Live delivery metrics and engagement rates

      - Bounce and complaint rate monitoring

      - Date-range filtering and tag-based segmentation

      - Export capabilities with domain-level breakdown

      - Email client distribution and device analytics


      ---


      ### 🎯 Content Analysis & Scoring


      **Pre-Send Spam Analysis**

      - Real-time content scoring before sending

      - Spam trigger detection in subject/HTML/text

      - Risk level assessment (low, medium, high, critical)

      - Actionable improvement suggestions


      **Content Categories**

      - Subject line optimization analysis

      - HTML/text content scanning

      - Link and image validation

      - Header compliance checking


      ---


      ### 📋 List Management


      **Suppression Lists**

      - Automatic bounce-based suppression (hard and soft)

      - Complaint-based suppression (spam reports)

      - Manual suppression entries via API

      - Whitelist management for test accounts


      **List Segmentation**

      - Tag-based organization

      - Custom metadata support

      - Bulk operations

      - Import/export capabilities


      ---


      ### 🖥️ IP Pool Management


      **Dedicated IP Pools**

      - Multiple IP pool support for segmentation

      - Automatic IP rotation for load balancing

      - Pool-level statistics

      - Geographic IP assignment options


      **IP Reputation Monitoring**

      - Real-time reputation tracking per IP

      - Automatic throttling on reputation issues

      - Blacklist monitoring and alerts

      - Deliverability scoring per IP


      **Automated IP Warm-Up**

      - Pre-configured warm-up schedules

      - Gradual volume increase over 2-4 weeks

      - Daily send limit management

      - Success tracking and adjustments


      ---


      ### 🔔 Webhooks & Integration


      **Event Webhooks**

      - Real-time push notifications for all events

      - Configurable event types (delivery, bounce, open, click, complaint)

      - Exponential backoff retry logic

      - HMAC signature verification for security


      **API-First Design**

      - RESTful architecture with JSON request/response

      - Comprehensive OpenAPI 3.1 specification

      - Interactive documentation with live testing

      - Detailed error responses with codes


      ---


      ### 🔐 Security & Compliance


      **Authentication & Access**

      - API key-based authentication with Bearer tokens

      - Automatic key rotation capability

      - IP whitelisting for API access

      - Rate limiting (1000 requests per 15 minutes)


      **Data Privacy**

      - GDPR compliance features and DPA available

      - Configurable data retention policies

      - One-click unsubscribe (RFC 8058 compliant)

      - Secure encrypted data storage


      **SSL/TLS Encryption**

      - All connections encrypted (HTTPS, TLS 1.2+)

      - STARTTLS for SMTP connections

      - Automatic certificate management

      - Custom tracking domain SSL support


      ---


      ### 🛠️ Developer Tools


      **Comprehensive Documentation**

      - OpenAPI 3.1 specification

      - Interactive API explorer

      - Code examples in cURL, Node.js, PHP, Python

      - Postman collection available


      **Testing & Monitoring**

      - Test email sending endpoint

      - Content scoring API for pre-send validation

      - Webhook testing capabilities

      - Detailed request/response logging

      - API performance metrics


      ---


      ### 💼 Use Cases


      **Transactional Emails**

      - Password resets

      - Order confirmations

      - Shipping notifications

      - Account alerts


      **Marketing Campaigns**

      - Newsletters

      - Promotional emails

      - Drip campaigns

      - A/B testing


      **Application Notifications**

      - User activity alerts

      - System notifications

      - Scheduled reports

      - Automated digests
  - name: FAQ
    x-displayName: FAQ
    description: >
      ### General Questions


      **Q: What is MailerLogic?**


      MailerLogic is a comprehensive email delivery platform designed for
      developers. We provide SMTP servers, REST APIs, tracking, analytics, and
      deliverability tools to help you send transactional and marketing emails
      at scale.



      **Q: How is MailerLogic different from other email services?**


      - Developer-first design built by developers

      - Real-time reputation monitoring across all IPs

      - Advanced content scoring with actionable suggestions

      - IP warm-up automation

      - Transparent pricing with no hidden fees


      **Q: What type of emails can I send?**


      You can send:


      - Transactional emails (password resets, receipts, notifications)

      - Marketing emails (newsletters, announcements, promotions)

      - Application notifications (user activity, system alerts)


      We do NOT allow spam, phishing, purchased/scraped lists, or illegal
      content.


      ---


      ### Account & Billing


      **Q: How do I sign up?**


      Contact support@mailerlogic.com to set up your account and receive your
      API credentials.


      **Q: What happens if I exceed my monthly limit?**


      Emails will be queued until your limit resets at the beginning of the next
      billing cycle. To continue sending immediately, upgrade your plan or
      purchase additional credits.


      **Q: Can I change my plan later?**


      Yes, you can upgrade or downgrade anytime. Changes take effect at the
      start of your next billing cycle.


      ---


      ### Domain Setup & Verification


      **Q: Why do I need to verify my domain?**


      Domain verification proves you own the domain and enables email
      authentication (SPF, DKIM, DMARC), which significantly improves
      deliverability and prevents spoofing.


      **Q: How long does DNS verification take?**


      DNS changes typically propagate within 1-4 hours, but can take up to 48
      hours in some cases.


      **Q: Do I need a subdomain or can I use my main domain?**


      We recommend using a subdomain like `mail.yourdomain.com` for sending.
      This:

      - Isolates email reputation from your main website

      - Allows independent DNS configuration

      - Provides better tracking and organization


      **Q: What if my domain verification fails?**


      Check that:

      - All DNS records are added correctly (no typos)

      - DNS changes have propagated (can take up to 48 hours)

      - There are no conflicting SPF or DKIM records

      - Your DNS provider supports TXT records


      Use the verify endpoint to see specific failure reasons.


      **Q: Can I use multiple domains?**


      Yes! You can add multiple domains to your account (based on your plan
      limits). Each domain has independent statistics and reputation.


      ---


      ### Sending Emails


      **Q: What's the difference between SMTP and REST API?**


      - **REST API**: Simple HTTP POST endpoint (`/api/send`) for sending emails
      with JSON payload - recommended for modern applications

      - **SMTP**: Standard email protocol, works with all email libraries and
      clients - better for legacy systems or when using existing SMTP libraries


      **Q: What SMTP ports do you support?**


      - **Port 587** (STARTTLS - recommended)

      - **Port 2525** (alternative STARTTLS)

      - Port 25 is not supported

      - Port 465 (SSL) may be added in the future


      **Q: Can I send attachments?**


      Yes, attachments are fully supported via SMTP. Maximum email size
      including attachments is 10MB.


      **Q: How many recipients can I send to per email?**


      Maximum 50 recipients per email. For larger lists, send multiple emails or
      use our bulk sending features.


      **Q: What's the sending rate limit?**


      Rate limits depend on your plan and IP reputation:

      - **Shared IPs**: 100-500 emails/minute

      - **Dedicated IPs**: 1000+ emails/minute


      **Q: Why are my emails going to spam?**


      Common causes:

      - Domain not verified (ensure SPF, DKIM, DMARC configured)

      - Poor content (use content scoring API)

      - Low engagement rates

      - High bounce/complaint rates

      - New IP needs warm-up


      ---


      ### Tracking & Analytics


      **Q: How does open tracking work?**


      We insert a tiny invisible 1x1 pixel image in your emails. When the
      recipient opens the email and images load, we record the open event.


      Limitations:

      - Requires images to be enabled

      - Privacy features in Apple Mail/Gmail may block tracking


      **Q: How does click tracking work?**


      We automatically rewrite all links to route through our tracking domain.
      When clicked, we record the event and redirect to the original URL
      (typically under 100ms).


      **Q: Can I disable tracking for specific emails?**


      Yes, tracking can be disabled:

      - Globally in account settings

      - Per domain

      - Per email (coming soon via API/SMTP headers)


      **Q: How long do you store tracking data?**


      - **Event data**: 90 days

      - **Aggregated statistics**: Indefinitely

      - **Detailed logs**: 30 days


      Enterprise plans can request extended retention.


      **Q: What timezone are timestamps in?**


      All timestamps are in UTC (Coordinated Universal Time) using ISO 8601
      format: `2024-03-15T14:30:00Z`


      ---


      ### Deliverability


      **Q: What is IP warm-up and do I need it?**


      IP warm-up gradually increases sending volume on a new IP address to build
      reputation with ISPs.


      You need it for:

      - New dedicated IPs

      - IPs idle for 30+ days

      - Significantly increased volume


      We automate this process over 2-4 weeks.


      **Q: How do I improve my sender reputation?**


      - Authenticate your domain (SPF, DKIM, DMARC)

      - Send quality content (use content scoring)

      - Maintain good list hygiene

      - Monitor engagement metrics

      - Follow proper IP warm-up schedules

      - Maintain steady sending patterns


      **Q: What should my bounce rate be?**


      - **Good**: Below 2%

      - **Acceptable**: 2-5%

      - **Poor**: Above 5%


      If your bounce rate exceeds 10%, we may pause sending to protect your
      reputation.


      **Q: What should my complaint rate be?**


      - **Good**: Below 0.1%

      - **Acceptable**: 0.1-0.5%

      - **Poor**: Above 0.5%


      Complaint rates above 1% may result in account suspension.


      **Q: How do suppression lists work?**


      Suppression lists prevent sending to addresses that have:

      - Hard bounced

      - Soft bounced repeatedly

      - Complained (marked as spam)

      - Unsubscribed

      - Been manually added


      Automatic suppression happens immediately.


      **Q: Can I whitelist specific addresses?**


      Yes, you can whitelist addresses to bypass suppression. Use this carefully
      for:

      - Test accounts

      - Internal email addresses

      - Verified opt-in addresses only


      ---


      ### Security & Compliance


      **Q: How secure is my data?**


      - All API requests use HTTPS (TLS 1.2+)

      - SMTP uses STARTTLS/SSL/TLS

      - API keys encrypted at rest

      - Database connections encrypted

      - Regular security audits


      **Q: Can I rotate my API key?**


      Yes, use the `/api/customer/rotate-key` endpoint. The old key is
      invalidated immediately, so update all applications with the new key.


      **Q: Can I rotate my SMTP password?**


      Yes, use the `/api/smtp-credentials/rotate` endpoint with your X-API-Key
      header.


      **Q: Is MailerLogic GDPR compliant?**


      Yes, we provide:

      - Data processing agreements (DPA)

      - Right to erasure (deletion)

      - Data export capabilities

      - Privacy-focused tracking options

      - Opt-out/unsubscribe management


      **Q: How do I implement unsubscribe?**


      We automatically add:

      - List-Unsubscribe header (standard email client unsubscribe)

      - One-click unsubscribe (RFC 8058 compliant)

      - Unsubscribe link


      You can also manage suppressions via API.


      **Q: What data do you collect?**


      We collect:

      - **Sending data**: From, to, subject, timestamps

      - **Tracking data**: Opens, clicks, IP addresses, user agents

      - **Event data**: Bounces, complaints, delivery status

      - **Account data**: Usage statistics, API access logs


      We do NOT store full email content or attachments.


      ---


      ### Technical Questions


      **Q: What programming languages do you support?**


      MailerLogic works with any language that supports SMTP (Python, Node.js,
      PHP, Ruby, Java, Go, C#) or HTTP/REST. Documentation includes examples in
      cURL, Node.js, Python, and PHP.


      **Q: Do you have SDKs or libraries?**


      Official SDKs coming soon. For now, use:

      - Standard SMTP libraries (Nodemailer, PHPMailer, Python smtplib)

      - HTTP clients for REST API calls


      **Q: What's your API rate limit?**


      1000 requests per 15 minutes per IP address.


      Rate limit headers included:

      - `X-RateLimit-Limit`: Request limit

      - `X-RateLimit-Remaining`: Requests remaining

      - `X-RateLimit-Reset`: Reset timestamp


      Contact support for higher limits.


      **Q: Do you have a sandbox environment?**


      Sandbox environment coming soon. For now, use:

      - Small test sends on production

      - Content scoring API for pre-send testing

      - Test domains with low volumes


      **Q: How do I test webhooks locally?**


      Use tools like:

      - **ngrok**: Creates public URLs for localhost

      - **RequestBin**: Captures webhook requests

      - **webhook.site**: Free webhook testing


      **Q: Can I use MailerLogic behind a firewall?**


      Yes, but ensure your firewall allows:

      - Outbound HTTPS (port 443) for API calls

      - Outbound SMTP (port 587 or 2525) for email sending


      **Q: What's your uptime SLA?**


      We target 99.9% uptime. Enterprise plans include:

      - SLA guarantees

      - Priority support

      - Status page notifications


      Status page: https://status.mailerlogic.com


      ---


      ### Troubleshooting


      **Q: Why can't I authenticate via SMTP?**


      Check:

      - Using correct SMTP credentials (from `/api/smtp-credentials`)

      - Using STARTTLS on port 587 or 2525

      - No firewall blocking outbound SMTP

      - Credentials not expired


      **Q: Why are my API requests failing with 401?**


      Possible causes:

      - Invalid API key (check key is correct and not expired)

      - Wrong header (use `Authorization: Bearer YOUR_KEY` for most endpoints)

      - Using a key from a different customer account


      **Q: Why am I getting 429 errors?**


      You've exceeded the rate limit (1000 requests per 15 minutes). Wait for
      the reset time indicated in the `X-RateLimit-Reset` header.


      **Q: Why aren't my opens/clicks being tracked?**


      Check:

      - Tracking enabled on your account

      - HTML email (tracking requires HTML)

      - Images enabled in recipient's email client (for opens)

      - Privacy features may block tracking (Apple Mail, Gmail)


      **Q: Why is my email still queued?**


      Emails may be queued due to:

      - **IP warm-up limits**: Daily sending limits during warm-up

      - **Domain throttling**: Respecting recipient domain rate limits

      - **Quota exceeded**: Monthly limit reached

      - **Reputation issues**: Automatic throttling due to bounces/complaints


      ---


      ### Support


      - **Email**: support@mailerlogic.com (24-hour response on business days)

      - **Documentation**: https://support.mailerlogic.com

      - **Status**: https://status.mailerlogic.com
  - name: Email Sending
    description: |
      Send transactional and marketing emails via REST API.
      Simple API for sending individual emails with full tracking support.
  - name: Profile
    description: |
      Manage your customer profile, view usage limits, and rotate API keys.
      Start here to understand your account settings and available resources.
  - name: SMTP
    description: |
      Get SMTP credentials for sending emails directly through our mail servers.
      Use these endpoints to retrieve and rotate your SMTP passwords.
  - name: Domains
    description: |
      Add and verify sender domains for email authentication.
      Configure SPF, DKIM, and DMARC records to improve deliverability.
  - name: Statistics
    description: >
      Access detailed email delivery and engagement metrics.

      Query sends, bounces, opens, clicks, and spam complaints with flexible
      date filters.
  - name: Events
    description: |
      Query granular email events and build custom analytics.
      Enterprise feature - must be enabled on your account.
  - name: Content Scoring
    description: |
      Analyze email content for spam patterns before sending.
      Get actionable feedback to improve deliverability scores.
  - name: Tracking
    description: >
      Public endpoints for open and click tracking.

      These are called automatically by email clients - no authentication
      required.
  - name: Webhooks
    description: |
      Receive real-time notifications for bounces and complaints.
      Configure these endpoints in your mail server or monitoring tools.
x-tagGroups:
  - name: Getting Started
    tags:
      - Quickstart Guide
      - Features Overview
      - FAQ
  - name: API Reference
    tags:
      - Email Sending
      - Profile
      - SMTP
      - Domains
      - Statistics
      - Content Scoring
      - Events
  - name: Public Endpoints
    tags:
      - Tracking
      - Webhooks
security:
  - BearerAuth: []
  - ApiKeyAuth: []
paths:
  /api/send:
    post:
      tags:
        - Email Sending
      summary: Send a single email
      description: >
        Send a single transactional or marketing email via REST API.


        **Simple API** for sending emails with:

        - Automatic queuing and delivery

        - Built-in tracking (opens & clicks)

        - Template variable support

        - Custom headers

        - Full bounce and complaint handling


        **Requirements:**

        - Verified sending domain

        - Active customer account

        - Valid API key


        **Auto-domain selection:** If you don't specify a `domain`, we'll
        automatically use your first verified domain.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - to
                - subject
              properties:
                domain:
                  type: string
                  description: >-
                    Sending domain (optional - auto-selects first verified
                    domain if omitted)
                  example: mail.yourdomain.com
                from:
                  type: string
                  format: email
                  description: From email address (defaults to noreply@domain)
                  example: hello@mail.yourdomain.com
                to:
                  type: string
                  format: email
                  description: Recipient email address
                  example: user@example.com
                reply_to:
                  type: string
                  format: email
                  description: Reply-to email address
                  example: support@yourdomain.com
                cc:
                  type: array
                  items:
                    type: string
                    format: email
                  description: CC recipients
                  example:
                    - manager@example.com
                bcc:
                  type: array
                  items:
                    type: string
                    format: email
                  description: BCC recipients (hidden from other recipients)
                  example:
                    - archive@yourdomain.com
                subject:
                  type: string
                  description: Email subject line
                  example: Welcome to our platform!
                html:
                  type: string
                  description: HTML email body
                  example: <h1>Welcome!</h1><p>Thanks for signing up.</p>
                text:
                  type: string
                  description: Plain text email body (fallback for non-HTML clients)
                  example: Welcome! Thanks for signing up.
                track_opens:
                  type: boolean
                  description: 'Enable open tracking (default: account setting)'
                  example: true
                track_clicks:
                  type: boolean
                  description: 'Enable click tracking (default: account setting)'
                  example: true
                headers:
                  type: object
                  description: Custom email headers
                  example:
                    X-Campaign-ID: campaign-123
                    X-User-ID: user-456
                tag:
                  type: string
                  description: Tag for organizing emails
                  example: welcome-series
                metadata:
                  type: object
                  description: Custom metadata (stored but not sent in email)
                  example:
                    user_id: '12345'
                    signup_source: homepage
            examples:
              simple:
                summary: Simple email
                value:
                  to: user@example.com
                  subject: Welcome to our platform!
                  html: <h1>Welcome!</h1><p>Thanks for signing up.</p>
                  text: Welcome! Thanks for signing up.
              full:
                summary: Full-featured email
                value:
                  domain: mail.yourdomain.com
                  from: hello@mail.yourdomain.com
                  to: user@example.com
                  reply_to: support@yourdomain.com
                  cc:
                    - manager@example.com
                  bcc:
                    - archive@yourdomain.com
                  subject: Your order has shipped!
                  html: >-
                    <h1>Order #12345 Shipped</h1><p>Track your package: <a
                    href='https://track.example.com'>Click here</a></p>
                  text: >-
                    Order #12345 Shipped. Track your package at:
                    https://track.example.com
                  track_opens: true
                  track_clicks: true
                  tag: transactional
                  headers:
                    X-Order-ID: '12345'
                  metadata:
                    order_id: '12345'
                    customer_tier: premium
      x-code-samples:
        - lang: cURL
          source: |
            curl -X POST https://api.mailerlogic.io/api/send \
              -H "X-API-Key: YOUR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "from": "hello@mail.yourdomain.com",
                "to": "user@example.com",
                "subject": "Welcome!",
                "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
                "text": "Welcome! Thanks for signing up."
              }'
        - lang: Node.js
          source: >
            const response = await fetch('https://api.mailerlogic.io/api/send',
            {
              method: 'POST',
              headers: {
                'X-API-Key': 'YOUR_API_KEY',
                'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                from: 'hello@mail.yourdomain.com',
                to: 'user@example.com',
                subject: 'Welcome!',
                html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
                text: 'Welcome! Thanks for signing up.'
              })
            });

            const result = await response.json();

            console.log('Email ID:', result.email_id);
        - lang: Python
          source: |
            import requests

            response = requests.post(
                'https://api.mailerlogic.io/api/send',
                headers={'X-API-Key': 'YOUR_API_KEY'},
                json={
                    'from': 'hello@mail.yourdomain.com',
                    'to': 'user@example.com',
                    'subject': 'Welcome!',
                    'html': '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
                    'text': 'Welcome! Thanks for signing up.'
                }
            )
            result = response.json()
            print('Email ID:', result['email_id'])
        - lang: PHP
          source: |
            <?php
            $ch = curl_init('https://api.mailerlogic.io/api/send');
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_HTTPHEADER, [
                'X-API-Key: YOUR_API_KEY',
                'Content-Type: application/json'
            ]);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
                'from' => 'hello@mail.yourdomain.com',
                'to' => 'user@example.com',
                'subject' => 'Welcome!',
                'html' => '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
                'text' => 'Welcome! Thanks for signing up.'
            ]));

            $response = curl_exec($ch);
            $result = json_decode($response, true);
            echo 'Email ID: ' . $result['email_id'];
      responses:
        '200':
          description: Email queued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  to:
                    type: string
                    format: email
                    description: Recipient email address
                    example: user@example.com
                  submitted_at:
                    type: string
                    format: date-time
                    description: ISO 8601 timestamp when email was queued
                    example: '2024-01-15T10:30:00Z'
                  message_id:
                    type: string
                    description: RFC 5322 Message-ID header value
                    example: <650e8400-e29b-41d4-a716-446655440000@mail.yourdomain.com>
                  email_id:
                    type: string
                    format: uuid
                    description: Unique email ID for tracking
                    example: 650e8400-e29b-41d4-a716-446655440000
                  status:
                    type: string
                    enum:
                      - queued
                    description: Current email status
                  message:
                    type: string
                    description: Success message
              example:
                to: user@example.com
                submitted_at: '2024-03-15T14:30:00Z'
                message_id: <550e8400-e29b-41d4-a716-446655440000@mail.yourdomain.com>
                email_id: 550e8400-e29b-41d4-a716-446655440000
                status: queued
                message: Email queued for delivery
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                missing_fields:
                  summary: Missing required fields
                  value:
                    error: Missing required fields
                    required:
                      - customer_id
                      - to
                      - subject
                    message: customer_id, to, and subject are required
                invalid_email:
                  summary: Invalid email address
                  value:
                    error: Invalid email address
                    message: The "to" field must be a valid email address
                domain_mismatch:
                  summary: From domain mismatch
                  value:
                    error: From domain mismatch
                    message: >-
                      The "from" email must use the sending domain:
                      mail.yourdomain.com
        '403':
          description: Forbidden - account or domain issue
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  reason:
                    type: string
              examples:
                account_paused:
                  summary: Customer account paused
                  value:
                    error: Customer account paused
                    reason: Payment overdue
                    message: Your account has been paused. Please contact support.
                domain_not_verified:
                  summary: Domain not verified
                  value:
                    error: Domain not verified
                    message: >-
                      Domain "mail.yourdomain.com" must be verified before
                      sending emails
        '404':
          description: Not found - customer or domain doesn't exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                customer_not_found:
                  summary: Customer not found
                  value:
                    error: Customer not found
                    message: >-
                      No customer found with id:
                      550e8400-e29b-41d4-a716-446655440000
                domain_not_found:
                  summary: Domain not found
                  value:
                    error: Domain not found
                    message: >-
                      Domain "mail.yourdomain.com" not found or not verified.
                      Add and verify your domain first.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              example:
                error: Internal server error
                message: Failed to process email send request
  /api/batch:
    post:
      tags:
        - Email Sending
      summary: Send batch of different emails
      description: >
        Send up to 500 **completely different emails** in a single API call.


        **Batch sending** where each email can have:

        - Different recipient

        - Different subject

        - Different content

        - Different settings


        Perfect for sending multiple transactional emails at once (order
        confirmations, password resets, etc.).


        **Limits:**

        - Maximum 500 emails per batch

        - Each email validated independently

        - Failed emails don't affect successful ones


        **Use cases:**

        - Sending different transactional emails simultaneously

        - Mixed email types in one API call

        - High-volume transactional sending


        **Not for:** Newsletter-style emails with same content → Use
        `/api/bulk-send` instead
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
                - emails
              properties:
                customer_id:
                  type: string
                  format: uuid
                  description: Your customer ID
                  example: 550e8400-e29b-41d4-a716-446655440000
                emails:
                  type: array
                  description: Array of emails to send (max 500)
                  maxItems: 500
                  items:
                    type: object
                    required:
                      - to
                      - subject
                    properties:
                      to:
                        type: string
                        format: email
                        description: Recipient email address
                        example: user@example.com
                      from:
                        type: string
                        format: email
                        description: From email (must use verified domain, optional)
                        example: hello@mail.yourdomain.com
                      domain:
                        type: string
                        description: Sending domain (optional - auto-selects if omitted)
                        example: mail.yourdomain.com
                      reply_to:
                        type: string
                        format: email
                        description: Reply-to address
                        example: support@yourdomain.com
                      cc:
                        type: array
                        items:
                          type: string
                          format: email
                        description: CC recipients
                      bcc:
                        type: array
                        items:
                          type: string
                          format: email
                        description: BCC recipients
                      subject:
                        type: string
                        description: Email subject
                        example: Your order has shipped
                      html:
                        type: string
                        description: HTML email body
                        example: <h1>Order shipped!</h1>
                      text:
                        type: string
                        description: Plain text body
                        example: Your order has shipped
                      track_opens:
                        type: boolean
                        description: Enable open tracking
                      track_clicks:
                        type: boolean
                        description: Enable click tracking
                      headers:
                        type: object
                        description: Custom headers
                      tag:
                        type: string
                        description: Tag for organizing
                      metadata:
                        type: object
                        description: Custom metadata
            example:
              customer_id: 550e8400-e29b-41d4-a716-446655440000
              emails:
                - to: user1@example.com
                  subject: 'Order #12345 Confirmed'
                  html: '<h1>Thanks for your order!</h1><p>Order #12345</p>'
                  text: 'Thanks for your order! Order #12345'
                  tag: order-confirmation
                  metadata:
                    order_id: '12345'
                - to: user2@example.com
                  subject: Password Reset Request
                  html: >-
                    <h1>Reset Password</h1><p><a href='https://...'>Click
                    here</a></p>
                  text: 'Reset your password: https://...'
                  tag: password-reset
                - to: user3@example.com
                  from: welcome@mail.yourdomain.com
                  subject: Welcome to our platform!
                  html: <h1>Welcome!</h1>
                  text: Welcome!
                  tag: welcome
      x-code-samples:
        - lang: cURL
          source: |
            curl -X POST https://api.mailerlogic.io/api/batch \
              -H "X-API-Key: YOUR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "customer_id": "550e8400-e29b-41d4-a716-446655440000",
                "emails": [
                  {
                    "to": "user1@example.com",
                    "subject": "Order Confirmed",
                    "html": "<h1>Order #12345</h1>",
                    "tag": "order"
                  },
                  {
                    "to": "user2@example.com",
                    "subject": "Password Reset",
                    "html": "<h1>Reset Password</h1>",
                    "tag": "auth"
                  }
                ]
              }'
        - lang: Node.js
          source: >
            const response = await fetch('https://api.mailerlogic.io/api/batch',
            {
              method: 'POST',
              headers: {
                'X-API-Key': 'YOUR_API_KEY',
                'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                customer_id: '550e8400-e29b-41d4-a716-446655440000',
                emails: [
                  {
                    to: 'user1@example.com',
                    subject: 'Order Confirmed',
                    html: '<h1>Order #12345</h1>',
                    tag: 'order'
                  },
                  {
                    to: 'user2@example.com',
                    subject: 'Password Reset',
                    html: '<h1>Reset Password</h1>',
                    tag: 'auth'
                  }
                ]
              })
            });

            const result = await response.json();

            console.log(`${result.queued} emails queued`);
        - lang: Python
          source: |
            import requests

            response = requests.post(
                'https://api.mailerlogic.io/api/batch',
                headers={'X-API-Key': 'YOUR_API_KEY'},
                json={
                    'customer_id': '550e8400-e29b-41d4-a716-446655440000',
                    'emails': [
                        {
                            'to': 'user1@example.com',
                            'subject': 'Order Confirmed',
                            'html': '<h1>Order #12345</h1>',
                            'tag': 'order'
                        },
                        {
                            'to': 'user2@example.com',
                            'subject': 'Password Reset',
                            'html': '<h1>Reset Password</h1>',
                            'tag': 'auth'
                        }
                    ]
                }
            )
            result = response.json()
            print(f"{result['queued']} emails queued")
        - lang: PHP
          source: |
            <?php
            $ch = curl_init('https://api.mailerlogic.io/api/batch');
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_HTTPHEADER, [
                'X-API-Key: YOUR_API_KEY',
                'Content-Type: application/json'
            ]);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
                'customer_id' => '550e8400-e29b-41d4-a716-446655440000',
                'emails' => [
                    [
                        'to' => 'user1@example.com',
                        'subject' => 'Order Confirmed',
                        'html' => '<h1>Order #12345</h1>',
                        'tag' => 'order'
                    ],
                    [
                        'to' => 'user2@example.com',
                        'subject' => 'Password Reset',
                        'html' => '<h1>Reset Password</h1>',
                        'tag' => 'auth'
                    ]
                ]
            ]));

            $response = curl_exec($ch);
            $result = json_decode($response, true);
            echo $result['queued'] . ' emails queued';
      responses:
        '200':
          description: Batch processed (may include partial failures)
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total emails in batch
                  queued:
                    type: integer
                    description: Successfully queued emails
                  failed:
                    type: integer
                    description: Failed emails
                  results:
                    type: array
                    description: Successfully queued emails
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: Index in original array
                        to:
                          type: string
                          format: email
                          description: Recipient
                        email_id:
                          type: string
                          format: uuid
                          description: Email ID for tracking
                        message_id:
                          type: string
                          description: Message-ID header
                        status:
                          type: string
                          enum:
                            - queued
                  errors:
                    type: array
                    description: Failed emails (only if any failed)
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: Index in original array
                        email:
                          type: string
                          description: Email address or identifier
                        error:
                          type: string
                          description: Error message
              examples:
                all_success:
                  summary: All emails queued
                  value:
                    total: 2
                    queued: 2
                    failed: 0
                    results:
                      - index: 0
                        to: user1@example.com
                        email_id: 550e8400-e29b-41d4-a716-446655440000
                        message_id: >-
                          <550e8400-e29b-41d4-a716-446655440000@mail.yourdomain.com>
                        status: queued
                      - index: 1
                        to: user2@example.com
                        email_id: 650e8400-e29b-41d4-a716-446655440001
                        message_id: >-
                          <650e8400-e29b-41d4-a716-446655440001@mail.yourdomain.com>
                        status: queued
                partial_success:
                  summary: Partial success (some failed).
                  value:
                    total: 3
                    queued: 2
                    failed: 1
                    results:
                      - index: 0
                        to: user1@example.com
                        email_id: 550e8400-e29b-41d4-a716-446655440000
                        message_id: >-
                          <550e8400-e29b-41d4-a716-446655440000@mail.yourdomain.com>
                        status: queued
                      - index: 2
                        to: user3@example.com
                        email_id: 750e8400-e29b-41d4-a716-446655440002
                        message_id: >-
                          <750e8400-e29b-41d4-a716-446655440002@mail.yourdomain.com>
                        status: queued
                    errors:
                      - index: 1
                        email: invalid-email
                        error: Invalid email address
        '400':
          description: Bad request or all emails failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                missing_fields:
                  summary: Missing required fields
                  value:
                    error: Missing required field
                    message: customer_id is required
                batch_size_exceeded:
                  summary: Too many emails
                  value:
                    error: Batch size exceeded
                    message: >-
                      Maximum 500 emails per batch. Use multiple requests for
                      larger batches.
                all_failed:
                  summary: All emails failed
                  value:
                    total: 2
                    queued: 0
                    failed: 2
                    errors:
                      - index: 0
                        email: user1@example.com
                        error: Missing subject field
                      - index: 1
                        email: user2@example.com
                        error: Domain not verified
        '403':
          description: Account paused
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  reason:
                    type: string
              example:
                error: Customer account paused
                reason: Payment overdue
                message: Your account has been paused. Please contact support.
        '404':
          description: Customer or domain not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                customer_not_found:
                  summary: Customer not found
                  value:
                    error: Customer not found
                    message: >-
                      No customer found with id:
                      550e8400-e29b-41d4-a716-446655440000
                no_verified_domains:
                  summary: No verified domains
                  value:
                    error: No verified domains
                    message: >-
                      No verified sending domains found. Add and verify a domain
                      first.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              example:
                error: Internal server error
                message: Failed to process batch send request
  /api/bulk-send:
    post:
      tags:
        - Email Sending
      summary: Send bulk emails (mail merge)
      description: >
        Send the **same email template** to multiple recipients with
        personalization.


        **Mail merge functionality** for:

        - Newsletters with personalized greetings

        - Marketing campaigns with custom variables

        - Bulk transactional emails with recipient-specific data


        **Features:**

        - Template variables: Use `{{variable}}` syntax in subject, HTML, and
        text

        - Per-recipient personalization via `vars` object

        - Automatic variable substitution for each recipient

        - Single template, many recipients


        **Limits:**

        - Recommended: Up to 10,000 recipients per call

        - Each recipient gets their own personalized copy


        **Use cases:**

        - Newsletter campaigns: "Hi {{name}}, check out our new {{product}}..."

        - Promotional emails with unique discount codes

        - Event invitations with personalized details


        **Not for:** Different emails to each recipient → Use `/api/batch`
        instead
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
                - subject
                - recipients
              properties:
                customer_id:
                  type: string
                  format: uuid
                  description: Your customer ID
                  example: 550e8400-e29b-41d4-a716-446655440000
                subject:
                  type: string
                  description: Email subject with optional variables {{name}}
                  example: Hello {{name}}! Your code is {{code}}
                html:
                  type: string
                  description: HTML email body with variables
                  example: '<h1>Hi {{name}}</h1><p>Your discount code: {{code}}</p>'
                text:
                  type: string
                  description: Plain text email body with variables
                  example: 'Hi {{name}}, Your discount code: {{code}}'
                from:
                  type: string
                  format: email
                  description: From email (must use verified domain, optional)
                  example: hello@mail.yourdomain.com
                domain:
                  type: string
                  description: Sending domain (optional - auto-selects if omitted)
                  example: mail.yourdomain.com
                reply_to:
                  type: string
                  format: email
                  description: Reply-to address
                  example: support@yourdomain.com
                track_opens:
                  type: boolean
                  description: 'Enable open tracking (default: true)'
                  default: true
                track_clicks:
                  type: boolean
                  description: 'Enable click tracking (default: true)'
                  default: true
                tag:
                  type: string
                  description: Tag for organizing/filtering emails
                  example: newsletter-2025-12
                recipients:
                  type: array
                  description: Array of recipients with personalization variables
                  items:
                    type: object
                    required:
                      - email
                    properties:
                      email:
                        type: string
                        format: email
                        description: Recipient email address
                        example: user@example.com
                      vars:
                        type: object
                        description: Variables for this recipient
                        example:
                          name: John Doe
                          code: SAVE20
                          product: Premium Plan
              example:
                customer_id: 550e8400-e29b-41d4-a716-446655440000
                subject: Hello {{name}}! Special offer inside
                html: >-
                  <h1>Hi {{name}}</h1><p>Use code <strong>{{code}}</strong> for
                  20% off!</p>
                text: Hi {{name}}, Use code {{code}} for 20% off!
                from: hello@mail.yourdomain.com
                track_opens: true
                track_clicks: true
                tag: holiday-sale-2025
                recipients:
                  - email: john@example.com
                    vars:
                      name: John
                      code: JOHN20
                  - email: jane@example.com
                    vars:
                      name: Jane
                      code: JANE20
      responses:
        '200':
          description: Bulk send request accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  queued:
                    type: integer
                    description: Number of emails queued
                    example: 2
                  results:
                    type: array
                    description: Array of queued email IDs
                    items:
                      type: object
                      properties:
                        email_id:
                          type: string
                          format: uuid
                        recipient:
                          type: string
                          format: email
                        message_id:
                          type: string
                        status:
                          type: string
                          example: queued
              example:
                success: true
                queued: 2
                results:
                  - email_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    recipient: john@example.com
                    message_id: <a1b2c3d4@mail.yourdomain.com>
                    status: queued
                  - email_id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                    recipient: jane@example.com
                    message_id: <b2c3d4e5@mail.yourdomain.com>
                    status: queued
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              example:
                error: Validation failed
                message: subject is required
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              example:
                error: Internal server error
                message: Failed to process bulk send request
  /api/customer/profile:
    get:
      tags:
        - Profile
      summary: Get customer profile
      description: |
        Retrieve your account profile including:
        - Current usage and remaining quota
        - Domain limits and tracking settings
        - API key (masked for security)

        **Use this to:**
        - Monitor monthly email usage
        - Check available resources
        - Verify account status
      security:
        - BearerAuth: []
      x-code-samples:
        - lang: cURL
          source: |
            curl https://api.mailerlogic.io/api/customer/profile \
              -H "Authorization: Bearer YOUR_API_KEY"
        - lang: Node.js
          source: >
            const response = await
            fetch('https://api.mailerlogic.io/api/customer/profile', {
              headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
            });

            const profile = await response.json();
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://api.mailerlogic.io/api/customer/profile',
                headers={'Authorization': 'Bearer YOUR_API_KEY'}
            )
            profile = response.json()
      responses:
        '200':
          description: Profile retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer:
                    $ref: '#/components/schemas/CustomerProfile'
              example:
                customer:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  name: Acme Corp
                  email: api@acme.com
                  status: active
                  monthly_email_limit: 100000
                  max_domains: 5
                  webhook_url: https://acme.com/webhooks/mailer
                  tracking_enabled: true
                  click_tracking_enabled: true
                  open_tracking_enabled: true
                  created_at: '2024-01-15T10:30:00Z'
                  current_domains: 3
                  emails_sent_this_month: 45230
                  remaining_emails: 54770
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - Profile
      summary: Update customer profile
      description: Update customer profile settings such as webhook URL.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_url:
                  type: string
                  format: uri
                  description: HTTPS URL for webhook notifications
                  example: https://your-domain.com/webhooks/mailerlogic
            example:
              webhook_url: https://acme.com/webhooks/mailer
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer:
                    $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/customer/rotate-key:
    post:
      tags:
        - Profile
      summary: Rotate API key
      description: >
        Generate a new API key for the customer account. The old key will be
        immediately invalidated.

        **Important:** Update all applications with the new key immediately.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: API key rotated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      API key rotated successfully. Update your applications
                      with the new key immediately.
                  api_key:
                    type: string
                    description: New API key
                    example: >-
                      ml_live_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                  customer:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      email:
                        type: string
                        format: email
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/smtp-credentials:
    get:
      tags:
        - SMTP
      summary: Get SMTP credentials
      description: >
        Retrieve your SMTP server credentials for sending emails.


        Use these credentials to configure your email client, application, or
        mail library.

        Port 587 (STARTTLS) is recommended for best compatibility.
      security:
        - ApiKeyAuth: []
      x-code-samples:
        - lang: cURL
          source: |
            curl https://api.mailerlogic.io/api/smtp-credentials \
              -H "X-API-Key: YOUR_API_KEY"
        - lang: Node.js
          source: >
            const response = await
            fetch('https://api.mailerlogic.io/api/smtp-credentials', {
              headers: { 'X-API-Key': 'YOUR_API_KEY' }
            });

            const credentials = await response.json();
        - lang: Python
          source: |
            import requests

            response = requests.get(
                'https://api.mailerlogic.io/api/smtp-credentials',
                headers={'X-API-Key': 'YOUR_API_KEY'}
            )
            credentials = response.json()
        - lang: PHP
          source: |
            $ch = curl_init('https://api.mailerlogic.io/api/smtp-credentials');
            curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_API_KEY']);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            $credentials = json_decode(curl_exec($ch), true);
      responses:
        '200':
          description: SMTP credentials retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMTPCredentials'
              example:
                customer_id: 550e8400-e29b-41d4-a716-446655440000
                customer_name: Acme Corp
                smtp_credentials:
                  host: smtp.mailerlogic.io
                  ports:
                    - 587
                    - 2525
                  recommended_port: 587
                  username: api@acme.com
                  password: smtp_a1b2c3d4e5f6...
                note: >-
                  Use these credentials to send emails via SMTP. Port 587 is
                  recommended for STARTTLS. Keep your password secure.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/smtp-credentials/rotate:
    post:
      tags:
        - SMTP
      summary: Rotate SMTP password
      description: >-
        Generate a new SMTP password. The old password will be immediately
        invalidated.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: SMTP password rotated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  smtp_credentials:
                    $ref: '#/components/schemas/SMTPCredentialsDetail'
                  warning:
                    type: string
                    example: >-
                      Update your SMTP clients with the new password. The old
                      password will no longer work.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/customer/domains:
    get:
      tags:
        - Domains
      summary: List all domains
      description: >
        Retrieve all domains registered to your account with their verification
        status.

        Use this to check which domains are ready for sending emails.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Domains retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/Domain'
              example:
                domains:
                  - id: d1234567-e89b-12d3-a456-426614174000
                    domain: mail.acme.com
                    verification_status: verified
                    dkim_selector: mail
                    spf_record: v=spf1 ip4:1.2.3.4 ~all
                    dmarc_record: v=DMARC1; p=quarantine; rua=mailto:dmarc@mail.acme.com
                    is_active: true
                    tags:
                      - production
                      - transactional
                    created_at: '2024-01-15T10:30:00Z'
                    verified_at: '2024-01-15T11:00:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - Domains
      summary: Add domain
      description: >
        Register a new domain for sending emails. This will generate DKIM keys
        and DNS records.

        After adding, use the DNS endpoint to get records that need to be
        configured.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  description: Fully qualified domain name
                  pattern: ^[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,}$
                  example: mail.acme.com
                tags:
                  type: array
                  items:
                    type: string
                  description: Optional tags for categorization
                  example:
                    - production
                    - transactional
      responses:
        '201':
          description: Domain created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    $ref: '#/components/schemas/DomainDetail'
        '400':
          description: Invalid domain or limit reached
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      error:
                        type: string
                        example: Invalid domain name
                  - type: object
                    properties:
                      error:
                        type: string
                        example: Domain limit reached. You have 5 of 5 domains.
                      current_domains:
                        type: integer
                      max_domains:
                        type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/customer/domains/{id}/dns:
    get:
      tags:
        - Domains
      summary: Get required DNS records
      description: >
        Get the DNS records you need to configure for this domain.

        Add these TXT records to your DNS provider to verify ownership and
        enable email authentication (SPF, DKIM, DMARC).
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Domain ID
      responses:
        '200':
          description: DNS records retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: string
                    example: mail.acme.com
                  dns_records:
                    type: array
                    items:
                      $ref: '#/components/schemas/DNSRecord'
              example:
                domain: mail.acme.com
                dns_records:
                  - type: TXT
                    name: _domainverify.mail.acme.com
                    value: a1b2c3d4e5f6g7h8
                    description: Domain verification record
                  - type: TXT
                    name: mail.acme.com
                    value: v=spf1 ip4:1.2.3.4 ~all
                    description: SPF record for email authentication
                  - type: TXT
                    name: mail._domainkey.mail.acme.com
                    value: v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3...
                    description: DKIM public key
                  - type: TXT
                    name: _dmarc.mail.acme.com
                    value: v=DMARC1; p=quarantine; rua=mailto:dmarc@mail.acme.com
                    description: DMARC policy
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/customer/domains/{id}/verify:
    post:
      tags:
        - Domains
      summary: Verify domain
      description: >-
        Verify DNS records for the domain. This checks SPF, DKIM, DMARC, and
        domain verification records.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Domain ID
      responses:
        '200':
          description: Verification completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  verified:
                    type: boolean
                  status:
                    type: string
                    enum:
                      - verified
                      - failed
                  results:
                    type: object
                    properties:
                      domain_verification:
                        type: boolean
                      spf:
                        type: boolean
                      dkim:
                        type: boolean
                      dmarc:
                        type: boolean
                  message:
                    type: string
              examples:
                success:
                  value:
                    verified: true
                    status: verified
                    results:
                      domain_verification: true
                      spf: true
                      dkim: true
                      dmarc: true
                    message: Domain verified successfully!
                failed:
                  value:
                    verified: false
                    status: failed
                    results:
                      domain_verification: true
                      spf: true
                      dkim: false
                      dmarc: true
                    message: Verification failed. Please check your DNS records.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/customer/domains/{id}:
    delete:
      tags:
        - Domains
      summary: Delete domain
      description: Remove a domain from the account. This cannot be undone.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Domain ID
      responses:
        '200':
          description: Domain deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Domain deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/customer/usage:
    get:
      tags:
        - Statistics
      summary: Get usage statistics
      description: Retrieve current month's email usage and delivery statistics.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Usage statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStatistics'
              example:
                current_month:
                  emails_sent: 45230
                  emails_delivered: 44850
                  emails_bounced: 280
                  emails_complained: 15
                  emails_opened: 22000
                  emails_clicked: 8500
                  delivery_rate: '99.16'
                  bounce_rate: '0.62'
                limits:
                  monthly_limit: 100000
                  remaining: 54770
                  used_percentage: '45.23'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/stats/outbound:
    get:
      tags:
        - Statistics
      summary: Get outbound statistics overview
      description: Overview of all outbound email statistics with optional date filtering.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
      responses:
        '200':
          description: Statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundStats'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/stats/outbound/sends:
    get:
      tags:
        - Statistics
      summary: Get send statistics
      description: Daily breakdown of emails sent with optional filtering.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/Tag'
      responses:
        '200':
          description: Send statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  days:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date-time
                        sent:
                          type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/stats/outbound/bounces:
    get:
      tags:
        - Statistics
      summary: Get bounce statistics
      description: Daily breakdown of bounced emails with hard/soft bounce classification.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/Tag'
      responses:
        '200':
          description: Bounce statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  days:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date-time
                        bounced:
                          type: integer
                        hard_bounce:
                          type: integer
                        soft_bounce:
                          type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/stats/outbound/spam:
    get:
      tags:
        - Statistics
      summary: Get spam complaint statistics
      description: Daily breakdown of spam complaints.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/Tag'
      responses:
        '200':
          description: Spam statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  days:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date-time
                        spam_complaints:
                          type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/stats/outbound/opens:
    get:
      tags:
        - Statistics
      summary: Get open statistics
      description: Daily breakdown of email opens (total and unique).
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/Tag'
      responses:
        '200':
          description: Open statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  days:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date-time
                        opens:
                          type: integer
                        unique_opens:
                          type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/stats/outbound/opens/platforms:
    get:
      tags:
        - Statistics
      summary: Get platform statistics
      description: >-
        Breakdown of email opens by email client platform (Gmail, Outlook, Apple
        Mail, etc.).
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
      responses:
        '200':
          description: Platform statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  platforms:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: Gmail
                        count:
                          type: integer
              example:
                platforms:
                  - name: Gmail
                    count: 12500
                  - name: Apple Mail
                    count: 8200
                  - name: Outlook
                    count: 6100
                  - name: Unknown
                    count: 1200
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/stats/outbound/clicks:
    get:
      tags:
        - Statistics
      summary: Get click statistics
      description: Daily breakdown of link clicks (total and unique).
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/Tag'
      responses:
        '200':
          description: Click statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  days:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date-time
                        clicks:
                          type: integer
                        unique_clicks:
                          type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/events:
    get:
      tags:
        - Events
      summary: Query email events
      description: >
        Query email events with advanced filtering.

        **Note:** This is an enterprise feature that must be enabled on your
        account.

        Requires `enable_event_tracking` and `enable_event_api` to be enabled.
      security:
        - BearerAuth: []
      parameters:
        - name: email_id
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by specific email ID
        - name: type
          in: query
          schema:
            type: string
            enum:
              - queued
              - sent
              - delivered
              - bounced
              - complained
              - opened
              - clicked
              - unsubscribed
          description: Filter by event type
        - name: recipient
          in: query
          schema:
            type: string
            format: email
          description: Filter by recipient email (partial match)
        - name: from
          in: query
          schema:
            type: string
            format: email
          description: Filter by sender email (partial match)
        - name: from_timestamp
          in: query
          schema:
            type: string
            format: date-time
          description: Filter events from this timestamp
        - name: to_timestamp
          in: query
          schema:
            type: string
            format: date-time
          description: Filter events until this timestamp
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Events retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailEvent'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Event API not enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - event_tracking_disabled
                      - event_api_disabled
                  message:
                    type: string
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/emails/{email_id}/events:
    get:
      tags:
        - Events
      summary: Get events for specific email
      description: >
        Retrieve all events for a specific email in chronological order.

        **Note:** This is an enterprise feature that must be enabled on your
        account.
      security:
        - BearerAuth: []
      parameters:
        - name: email_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Email ID
      responses:
        '200':
          description: Email events retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  email_id:
                    type: string
                    format: uuid
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailEvent'
                  timeline:
                    type: array
                    items:
                      type: object
                      properties:
                        event_type:
                          type: string
                        timestamp:
                          type: string
                          format: date-time
                        status:
                          type: string
                        details:
                          type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Event API not enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '404':
          description: Email not found or access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Email not found or access denied
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/content-score:
    post:
      tags:
        - Content Scoring
      summary: Analyze email content
      description: >
        Test your email content for spam triggers before sending.

        Get a deliverability score (0-100, higher is better) with specific
        issues and suggestions for improvement.


        **Use this to:**

        - Check emails before sending campaigns

        - Improve inbox placement rates

        - Identify problematic content patterns


        **Rate Limit:** Subject to monthly quota (default: 1000 checks/month)
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subject:
                  type: string
                  description: Email subject line
                  maxLength: 1000
                html:
                  type: string
                  description: HTML email content
                text:
                  type: string
                  description: Plain text email content
              required:
                - subject
              example:
                subject: Your Monthly Newsletter
                html: >-
                  <html><body><h1>Hello!</h1><p>Check out our latest
                  updates...</p></body></html>
                text: Hello! Check out our latest updates...
      responses:
        '200':
          description: Content analyzed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentScoreResult'
              example:
                status: ok
                score: 92
                risk_level: low
                matches:
                  - rule_code: EXCESSIVE_CAPS
                    severity: low
                    category: formatting
                    message: Subject line contains excessive capital letters
                    location: subject
                suggestions:
                  - Reduce capitalization in subject line
                  - Add a plain-text version of your email
                usage:
                  used: 145
                  limit: 1000
                  period: monthly
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  error:
                    type: string
                    example: invalid_request
                  message:
                    type: string
                    example: Subject, HTML, or text is required.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  error:
                    type: string
                    example: unauthorized
                  message:
                    type: string
                    example: >-
                      Authentication required. Use "Authorization: Bearer
                      <customer_api_key>" header.
        '403':
          description: Account suspended
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  error:
                    type: string
                    example: account_suspended
                  message:
                    type: string
        '429':
          description: Quota exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  error:
                    type: string
                    example: spam_check_quota_exceeded
                  message:
                    type: string
                    example: You have reached your monthly spam check limit.
                  usage:
                    type: object
                    properties:
                      used:
                        type: integer
                      limit:
                        type: integer
                      period:
                        type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  error:
                    type: string
                    example: internal_error
                  message:
                    type: string
  /track/o/{token}:
    get:
      tags:
        - Tracking
      summary: Track email open
      description: |
        Open tracking pixel endpoint. Returns a 1x1 transparent GIF.
        This endpoint is embedded in emails and called when the email is opened.
        **Public endpoint - no authentication required.**
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Encrypted tracking token
      security: []
      responses:
        '200':
          description: Tracking pixel returned
          content:
            image/gif:
              schema:
                type: string
                format: binary
  /track/c/{token}:
    get:
      tags:
        - Tracking
      summary: Track link click
      description: >
        Click tracking redirect endpoint. Logs the click and redirects to the
        original URL.

        **Public endpoint - no authentication required.**
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Encrypted tracking token containing email_id and target URL
      security: []
      responses:
        '302':
          description: Redirect to target URL
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: Original URL from the email
  /track/u/{token}:
    get:
      tags:
        - Tracking
      summary: Unsubscribe (manual)
      description: |
        Manual unsubscribe endpoint. Shows a confirmation page.
        **Public endpoint - no authentication required.**
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Encrypted unsubscribe token
      security: []
      responses:
        '200':
          description: Unsubscribe confirmation page
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Invalid or expired token
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - Tracking
      summary: One-click unsubscribe (RFC 8058)
      description: |
        One-click unsubscribe endpoint per RFC 8058.
        Email clients can call this to instantly unsubscribe users.
        **Public endpoint - no authentication required.**
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Encrypted unsubscribe token
      security: []
      responses:
        '200':
          description: Unsubscribed successfully
          content:
            text/plain:
              schema:
                type: string
                example: Unsubscribed successfully
        '400':
          description: Invalid token
          content:
            text/plain:
              schema:
                type: string
                example: Invalid token
  /webhooks/bounce:
    post:
      tags:
        - Webhooks
      summary: Receive bounce notifications
      description: >
        Webhook endpoint for receiving bounce notifications from mail servers or
        monitoring services.

        **Public endpoint - configure this URL in your mail server or monitoring
        service.**


        The system will process the bounce and update email status
        automatically.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emailId
              properties:
                emailId:
                  type: string
                  format: uuid
                  description: ID of the bounced email
                bounceType:
                  type: string
                  enum:
                    - hard
                    - soft
                  description: Type of bounce
                reason:
                  type: string
                  description: Bounce reason or error message
                recipientEmail:
                  type: string
                  format: email
                  description: Recipient that bounced
                timestamp:
                  type: string
                  format: date-time
                customData:
                  type: object
                  description: Additional bounce metadata
              example:
                emailId: 550e8400-e29b-41d4-a716-446655440000
                bounceType: hard
                reason: 550 5.1.1 User unknown
                recipientEmail: bounced@example.com
                timestamp: '2024-03-15T14:30:00Z'
      responses:
        '200':
          description: Bounce processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: emailId is required
        '500':
          description: Failed to process bounce
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Failed to process bounce
  /webhooks/complaint:
    post:
      tags:
        - Webhooks
      summary: Receive spam complaint notifications
      description: >
        Webhook endpoint for receiving spam complaint notifications.

        **Public endpoint - configure this URL in your mail server or feedback
        loop service.**
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emailId
              properties:
                emailId:
                  type: string
                  format: uuid
                  description: ID of the complained email
                recipientEmail:
                  type: string
                  format: email
                  description: Recipient who complained
                complaintType:
                  type: string
                  description: Type of complaint
                  example: abuse
                timestamp:
                  type: string
                  format: date-time
                feedbackType:
                  type: string
                  enum:
                    - abuse
                    - fraud
                    - virus
                    - other
                customData:
                  type: object
              example:
                emailId: 550e8400-e29b-41d4-a716-446655440000
                recipientEmail: user@example.com
                complaintType: abuse
                feedbackType: abuse
                timestamp: '2024-03-15T14:45:00Z'
      responses:
        '200':
          description: Complaint processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Failed to process complaint
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >
        Customer API Key using Bearer token authentication.


        Example:

        ```

        Authorization: Bearer ml_live_1234567890abcdef...

        ```


        Get your API key from your customer dashboard or use the
        `/api/customer/rotate-key` endpoint.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        Customer API Key in X-API-Key header (used for SMTP and statistics
        endpoints).


        Example:

        ```

        X-API-Key: ml_live_1234567890abcdef...

        ```
  parameters:
    FromDate:
      name: fromdate
      in: query
      description: Start date for filtering (ISO 8601)
      schema:
        type: string
        format: date-time
      example: '2024-03-01T00:00:00Z'
    ToDate:
      name: todate
      in: query
      description: End date for filtering (ISO 8601)
      schema:
        type: string
        format: date-time
      example: '2024-03-31T23:59:59Z'
    Tag:
      name: tag
      in: query
      description: Filter by email tag
      schema:
        type: string
      example: newsletter
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        status:
          type: string
          enum:
            - active
            - suspended
            - pending
        webhook_url:
          oneOf:
            - type: string
              format: uri
            - type: 'null'
        tracking_enabled:
          type: boolean
        click_tracking_enabled:
          type: boolean
        open_tracking_enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
    CustomerProfile:
      allOf:
        - $ref: '#/components/schemas/Customer'
        - type: object
          properties:
            monthly_email_limit:
              type: integer
              description: Monthly email sending limit
            max_domains:
              type: integer
              description: Maximum number of domains allowed
            current_domains:
              type: integer
              description: Current number of domains registered
            emails_sent_this_month:
              type: integer
              description: Emails sent in current month
            remaining_emails:
              type: integer
              description: Remaining emails for current month
    Domain:
      type: object
      properties:
        id:
          type: string
          format: uuid
        domain:
          type: string
        verification_status:
          type: string
          enum:
            - pending
            - verified
            - failed
        dkim_selector:
          type: string
        spf_record:
          type: string
        dmarc_record:
          type: string
        is_active:
          type: boolean
        tags:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        verified_at:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
    DomainDetail:
      allOf:
        - $ref: '#/components/schemas/Domain'
        - type: object
          properties:
            verification_token:
              type: string
            dkim_private_key:
              type: string
              description: DKIM private key (keep secure!)
            dkim_public_key:
              type: string
    DNSRecord:
      type: object
      properties:
        type:
          type: string
          enum:
            - TXT
            - MX
            - CNAME
        name:
          type: string
          description: DNS record name/host
        value:
          type: string
          description: DNS record value
        description:
          type: string
          description: Human-readable description
    SMTPCredentials:
      type: object
      properties:
        customer_id:
          type: string
          format: uuid
        customer_name:
          type: string
        smtp_credentials:
          $ref: '#/components/schemas/SMTPCredentialsDetail'
        note:
          type: string
    SMTPCredentialsDetail:
      type: object
      properties:
        host:
          type: string
          description: SMTP server hostname
          example: smtp.mailerlogic.io
        ports:
          type: array
          items:
            type: integer
          description: Available SMTP ports
        recommended_port:
          type: integer
          description: Recommended port (usually 587 for STARTTLS)
        username:
          type: string
          description: SMTP username (customer email)
        password:
          type: string
          description: SMTP password
    UsageStatistics:
      type: object
      properties:
        current_month:
          type: object
          properties:
            emails_sent:
              type: integer
            emails_delivered:
              type: integer
            emails_bounced:
              type: integer
            emails_complained:
              type: integer
            emails_opened:
              type: integer
            emails_clicked:
              type: integer
            delivery_rate:
              type: string
              description: Percentage as string (e.g., "99.16")
            bounce_rate:
              type: string
              description: Percentage as string
        limits:
          type: object
          properties:
            monthly_limit:
              type: integer
            remaining:
              type: integer
            used_percentage:
              type: string
              description: Percentage as string
    OutboundStats:
      type: object
      properties:
        sent:
          type: integer
        delivered:
          type: integer
        bounced:
          type: integer
        failed:
          type: integer
        opens:
          type: integer
        unique_opens:
          type: integer
        clicks:
          type: integer
        unique_clicks:
          type: integer
        spam_complaints:
          type: integer
        tracked:
          type: integer
          description: Total tracked events (opens + clicks)
    EmailEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email_id:
          type: string
          format: uuid
        customer_id:
          type: string
          format: uuid
        event_type:
          type: string
          enum:
            - queued
            - sent
            - delivered
            - bounced
            - complained
            - opened
            - clicked
            - unsubscribed
        status:
          type: string
        recipient:
          type: string
          format: email
        from:
          type: string
          format: email
        timestamp:
          type: string
          format: date-time
        event_data:
          type: object
          description: Additional event metadata (may be redacted based on privacy level)
        created_at:
          type: string
          format: date-time
    ContentScoreResult:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - error
        score:
          type: integer
          minimum: 0
          maximum: 100
          description: Content score (0-100, higher is better)
        risk_level:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
          description: Risk level assessment
        matches:
          type: array
          items:
            type: object
            properties:
              rule_code:
                type: string
              severity:
                type: string
                enum:
                  - low
                  - medium
                  - high
                  - critical
              category:
                type: string
              message:
                type: string
              location:
                type: string
                enum:
                  - subject
                  - html
                  - text
        suggestions:
          type: array
          items:
            type: string
          description: Actionable suggestions to improve score
        usage:
          type: object
          properties:
            used:
              type: integer
            limit:
              type: integer
            period:
              type: string
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
          description: Total number of items
        pages:
          type: integer
          description: Total number of pages
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code or message
  responses:
    UnauthorizedError:
      description: Authentication failed or missing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Invalid API key
    ForbiddenError:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Account is suspended
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Domain not found
    BadRequestError:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Invalid domain name
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: An unexpected error occurred
