dovemails-com Send API

openapi: 3.2.0
info:
  title: Dovemails Send API
  description: '**Dovemails** is an email sending platform — a transactional and marketing

    email API.


    This page documents the **public, API-key surface**: sending, messages, events and

    the marketing resources (contacts, segments, templates, broadcasts, automations).

    Everything else the dashboard uses (analytics, webhooks, billing, admin) is

    intentionally not published here.


    ### Base URL


    All paths below are relative to your own install, e.g. `https://your-instance`.


    ### Authentication


    Send an API key created in the dashboard (sidebar → **API Keys**, `/esp/api-keys`) as a

    Bearer token. Every key starts with `sk_`; there is no separate live/test prefix — a

    test key is one you created with the **sandbox** flag, and it looks identical:


    ```

    Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    ```


    Click **Authorize** above and paste the key to try any endpoint from this page.


    A missing or malformed header returns `401 {"detail": "Missing API key"}`; a key that

    is unknown, revoked or expired returns `401 {"detail": "Invalid API key"}`.


    Some endpoints are reachable only with a **dashboard session** (the browser JWT) and

    *cannot* be called with an API key — those are called out in their tag description.


    ### Correlating a request


    Every response carries a `Dovemails-Request-Id` header — a short hex id for that one

    call. Quote it in a support request: it is what ties the call to the per-recipient

    record of what each address in it did or didn''t get queued, including a `422` that was

    refused before the send ran.


    The id is per HTTP call, so a retry gets a new one.


    ### Quickstart


    ```bash

    curl -X POST https://your-instance/api/v1/send \n -H "Authorization: Bearer $DOVEMAILS_API_KEY" \n -H "Content-Type: application/json" \n -d ''{"from":"hello@yourdomain.com","to":"you@example.com",

    "subject":"Hello from Dovemails","text":"It works."}''

    ```


    Longer guides live in the repository: `docs/quickstart.md`, `docs/sending.md`,

    `docs/webhooks.md`. The raw schema is at `/openapi.json`.'
  version: 1.1.0
tags:
- name: Send
paths:
  /api/v1/send:
    post:
      tags:
      - Send
      summary: Send
      description: 'Send a transactional or marketing email.


        Branch on `status`, not the HTTP code: `queued`, or `pending_review` (202)

        when the sending inbox''s protection policy holds the message for a human —

        the reply then also carries `review_id`. See "Human approval" in the guide.


        Pass an `Idempotency-Key` header to make retries safe: two requests

        with the same key (for the same API key''s user) are guaranteed to

        create at most one message — the second either replays the first

        response verbatim, or gets 409 if the first is still in flight.


        If the API key is in sandbox mode, the message is never actually

        delivered — see `POST /apikeys`.


        Recipients: `"to"` takes a string or a list, plus optional `"cc"` and

        `"bcc"` lists (50 recipients per send, all fields combined). One message

        is created per recipient, so suppression, tracking and quota stay

        per-recipient. Bcc addresses appear in no copy''s headers. A plain

        single-recipient send returns `{"status","message_id","id"}` as before;

        any multi-recipient send returns `{"status", "recipients": [...]}` with a

        per-address verdict, and one suppressed address does not stop the rest.


        Attachments (transactional stream only — marketing sends are rejected,

        for deliverability): `"attachments": [{"name": "invoice.pdf",

        "content_b64": "", "content_type": "application/pdf"}]`. The

        total decoded size, multiplied by the recipient count (every copy carries

        the attachment), is capped by `RELAY_MAX_ATTACHMENT_MB` (default 10); over

        the cap returns 413.


        `"reply_to"` sets a single Reply-To address. `"headers"` adds custom

        headers, restricted to `X-*` names — anything else (From, Subject,

        Received, DKIM-Signature, List-*, ...) is rejected 422 naming the header,

        as is any value containing a line break, more than 20 headers, or a header

        line over the RFC 5322 998-octet limit. `"metadata"` is an arbitrary JSON

        object (max 2 KB serialized) stored with the message and echoed back

        verbatim in every webhook payload and in `GET /api/v1/messages/{id}`.


        `"template_id"` sends a stored template (404 if it isn''t yours) and cannot

        be combined with `"html"`/`"text"` (422). `"variables"` fills its

        `{{placeholders}}`; every placeholder the template contains is required, and

        a missing one returns 422. The template''s own subject wins when it

        has one. Values are HTML-escaped in the HTML body (they are usually your own

        end users'' data), and the rendered result is capped like an attachment.


        `"send_at"` (ISO 8601) holds the message in the queue until that time — it

        must be in the future and at most 30 days out, otherwise 422.


        If sending on the account is paused pending review, every send returns

        **403** `Sending is paused pending review. Contact hello@dovemails.com.`

        Waiting does not clear it — reply to that address and it is lifted by hand.

        New accounts must also pass `"unsubscribe_url"` on the `marketing` stream;

        without it the send returns **422** `marketing sends require

        unsubscribe_url`. Established accounts and dashboard broadcasts are exempt.


        **curl**

        ```

        curl https://app.dovemails.com/api/v1/send \n -H "Authorization: Bearer sk_..." \n -H "Content-Type: application/json" \n -H "Idempotency-Key: unique-per-attempt" \n -d ''{"from": "you@yourdomain.com", "to": "them@example.com",

        "subject": "Hello", "html": "

        Hi!

        "}''

        ```


        **Python**

        ```python

        import requests

        requests.post("https://app.dovemails.com/api/v1/send",

        headers={"Authorization": "Bearer sk_...", "Idempotency-Key": "unique-per-attempt"},

        json={"from": "you@yourdomain.com", "to": "them@example.com",

        "subject": "Hello", "html": "

        Hi!

        "})

        ```


        **Node**

        ```js

        await fetch("https://app.dovemails.com/api/v1/send", {

        method: "POST",

        headers: { Authorization: "Bearer sk_...", "Idempotency-Key": "unique-per-attempt",

        "Content-Type": "application/json" },

        body: JSON.stringify({ from: "you@yourdomain.com", to: "them@example.com",

        subject: "Hello", html: "

        Hi!

        " }),

        });

        ```'
      operationId: send_api_v1_send_post
      security:
      - ApiKey: []
      - DashboardSession: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResult'
        '202':
          description: Held for human review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/send/batch:
    post:
      tags:
      - Send
      summary: Send Batch
      description: Send up to 500 recipie...
      operationId: postApiV1SendBatch
      x-operation-id-source: derived
components:
  schemas:
    HTTPValidationError:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    SendResult:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    SendRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true