> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendr.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending Email

> Send an email to one or multiple recipients

Send an HTML email to one or multiple recipients. Delivery is asynchronous: a successful request returns **`202 Accepted`** with a `batchId`, and the emails are processed in the background.

Maximum **500 recipients** per API call. Unsubscribed recipients are filtered out automatically before sending and do not count toward your sending limit.

### Request

The body has two parts:

* `recipients` — array of `{ email, name? }` (1–500 items, `email` required).
* `emailConfig` — message configuration.

**Required `emailConfig` fields:** `subject`, `from`, `body` (HTML).

**Optional `emailConfig` fields:**

| Field            | Notes                                                                          |
| ---------------- | ------------------------------------------------------------------------------ |
| `fromName`       | Sender display name                                                            |
| `companyName`    | Per-send override; falls back to your tenant's saved company name              |
| `companyAddress` | Per-send override; falls back to your tenant's saved mailing address           |
| `companyWebsite` | Per-send override (valid URL); falls back to your tenant's saved website       |
| `returnPath`     | Return-Path / bounce address                                                   |
| `unsubscribeUrl` | May contain the `{{email}}` placeholder, replaced with the recipient's address |
| `trackOpens`     | Defaults to `true`                                                             |
| `trackClicks`    | Defaults to `true`                                                             |

### Response

* `202 Accepted`: Processing started. Returns `status: "IN PROGRESS"`, `message`, `batchId`, and a `limits` object.
* `400 Bad Request`: Invalid request parameters or malformed JSON
* `401 Unauthorized`: Authentication required or invalid API key
* `500 Internal Server Error`: Unexpected server error

<Note>
  The response `limits` object shows your sending-quota usage for this request (`limit`, `used`, `remaining`, `requested`). `requested` reflects the recipient count **after** unsubscribed addresses are filtered out.
</Note>

<Note>
  Authenticate with your API key in the `Authorization` header. The key must have the `emailSend` scope.
</Note>


## OpenAPI

````yaml POST /email
openapi: 3.1.0
info:
  title: Email Service API
  description: API for sending and managing email communications
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://sending.sendrapp.org
    description: Email Sending API
  - url: https://stats.sendrapp.org
    description: Statistics API
  - url: https://logs.sendrapp.org
    description: Logs API
  - url: http://localhost:3001
    description: Local Development
security:
  - apiKeyAuth: []
paths:
  /email:
    post:
      summary: Send Email
      description: Send an email to one or multiple recipients
      requestBody:
        description: >-
          Email configuration and recipients. Maximum 500 recipients per API
          call. Unsubscribed recipients are filtered out automatically and do
          not count toward your sending limit.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRequest'
      responses:
        '202':
          description: >-
            Accepted — email processing has started. Delivery happens
            asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailResponse'
        '400':
          description: Invalid request parameters (validation error) or malformed JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      servers:
        - url: https://sending.sendrapp.org
          description: Email Sending API
        - url: http://localhost:3001
          description: Local Development
components:
  schemas:
    EmailRequest:
      type: object
      required:
        - recipients
        - emailConfig
      properties:
        recipients:
          type: array
          description: List of email recipients. Maximum 500 per call.
          items:
            type: object
            required:
              - email
            properties:
              email:
                type: string
                format: email
                description: Recipient email address
              name:
                type: string
                description: Recipient name (optional)
        emailConfig:
          type: object
          required:
            - subject
            - from
            - body
          properties:
            subject:
              type: string
              description: Email subject (required)
            from:
              type: string
              description: Sender email address (required)
            fromName:
              type: string
              description: Sender display name (optional)
            body:
              type: string
              description: HTML email content (required)
            companyName:
              type: string
              maxLength: 255
              description: >-
                Optional per-send override of the company name. Falls back to
                your tenant's saved companyName.
            companyAddress:
              type: string
              maxLength: 500
              description: >-
                Optional per-send override of the company mailing address. Falls
                back to your tenant's saved companyMailingAddress.
            companyWebsite:
              type: string
              format: uri
              description: >-
                Optional per-send override of the company website URL. Falls
                back to your tenant's saved companyWebsite.
            returnPath:
              type: string
              format: email
              description: Optional Return-Path (bounce) address.
            unsubscribeUrl:
              type: string
              description: >-
                Optional unsubscribe URL. May contain the {{email}} placeholder,
                which is substituted with the recipient's address.
            trackOpens:
              type: boolean
              default: true
              description: Whether to track opens. Defaults to true.
            trackClicks:
              type: boolean
              default: true
              description: Whether to track link clicks. Defaults to true.
    EmailResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - IN PROGRESS
          description: Processing status
        message:
          type: string
          description: Status message, e.g. "Email processing started"
        batchId:
          type: string
          description: Identifier for this send batch (e.g. batch_1782700000000_ab12cd34)
        limits:
          type: object
          description: Your sending-limit usage for this request
          properties:
            limit:
              type: integer
              description: Total quota for the current period
            used:
              type: integer
              description: Quota already used
            remaining:
              type: integer
              description: Remaining quota
            requested:
              type: integer
              description: Recipients requested in this call (after unsubscribe filtering)
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````