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

# Send bulk emails

> Send up to 100 individual emails in a single request. Each email in the array is independent — with its own recipient, subject, content, and optional template. The request body can be either an object with an `emails` key, or a plain JSON array of email objects. Each email follows the same rules as the single send endpoint: `from`, `subject`, and `html`/`text` are required unless a template is provided. Results are returned in the same order as the input array, with each entry indicating success (with an `id`) or error (with an error message).



## OpenAPI

````yaml POST /emails/bulk
openapi: 3.1.0
info:
  title: SendKit API
  description: The SendKit API allows you to send transactional emails programmatically.
  version: 1.0.0
servers:
  - url: https://api.sendkit.dev
security:
  - bearerAuth: []
paths:
  /emails/bulk:
    post:
      tags:
        - Emails
      summary: Send bulk emails
      description: >-
        Send up to 100 individual emails in a single request. Each email in the
        array is independent — with its own recipient, subject, content, and
        optional template. The request body can be either an object with an
        `emails` key, or a plain JSON array of email objects. Each email follows
        the same rules as the single send endpoint: `from`, `subject`, and
        `html`/`text` are required unless a template is provided. Results are
        returned in the same order as the input array, with each entry
        indicating success (with an `id`) or error (with an error message).
      operationId: sendBulkEmails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendBulkEmailRequest'
      responses:
        '202':
          description: Emails accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendBulkEmailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                name: rate_limit_exceeded
                message: Rate limit exceeded. Please retry after 30 seconds.
components:
  schemas:
    SendBulkEmailRequest:
      type: object
      required:
        - emails
      properties:
        emails:
          type: array
          minItems: 1
          maxItems: 100
          description: >-
            Array of email objects to send. Each email is independent with its
            own recipient, content, and options. You can also send a plain JSON
            array (without the `emails` wrapper key).
          items:
            $ref: '#/components/schemas/BulkEmailItem'
    SendBulkEmailResponse:
      type: object
      properties:
        data:
          type: array
          description: >-
            Array of results in the same order as the input. Each entry
            indicates success or error.
          items:
            oneOf:
              - type: object
                description: Successful email.
                properties:
                  status:
                    type: string
                    enum:
                      - success
                    example: success
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier of the created email.
                    example: 550e8400-e29b-41d4-a716-446655440000
              - type: object
                description: Failed email.
                properties:
                  status:
                    type: string
                    enum:
                      - error
                    example: error
                  error:
                    type: string
                    description: Error code.
                    example: domain_not_verified
                  message:
                    type: string
                    description: Human-readable error message.
                    example: The from address domain is not verified.
    ErrorResponse:
      type: object
      properties:
        name:
          type: string
          description: Error type identifier.
          example: validation_error
        message:
          type: string
          description: Human-readable error message.
          example: The from address domain is not verified.
    BulkEmailItem:
      type: object
      required:
        - to
      properties:
        from:
          type: string
          description: >-
            Sender email address. Required unless a template is provided. Must
            belong to a verified domain.
          example: Your Name <hello@yourdomain.com>
        to:
          type: string
          description: >-
            Recipient email address. Supports display name format (e.g. "Bob
            <bob@example.com>").
          example: user@example.com
        subject:
          type: string
          maxLength: 998
          description: Email subject line. Required unless a template is provided.
          example: Welcome to SendKit
        html:
          type: string
          description: >-
            HTML body of the email. Required if `text` is not provided and no
            template is used.
          example: <h1>Hello!</h1><p>Welcome aboard.</p>
        text:
          type: string
          description: >-
            Plain text body of the email. Required if `html` is not provided and
            no template is used.
          example: Hello! Welcome aboard.
        cc:
          type: array
          items:
            type: string
          description: Carbon copy recipients.
        bcc:
          type: array
          items:
            type: string
          description: Blind carbon copy recipients.
        reply_to:
          type: array
          items:
            type: string
          description: Reply-to email addresses.
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom email headers as key-value pairs.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: Metadata tags as key-value pairs.
        scheduled_at:
          type: string
          format: date-time
          description: >-
            Schedule the email for future delivery. Must be a future ISO 8601
            timestamp.
        attachments:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Attachment'
          description: File attachments. Maximum 10 per email.
        template:
          type:
            - object
            - 'null'
          description: Use a published template instead of providing html/text directly.
          properties:
            id:
              type: string
              format: uuid
              description: >-
                The template ID. Must be a published template belonging to your
                account.
            variables:
              type: object
              additionalProperties:
                type: string
              description: Template variable values.
          required:
            - id
    Tag:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          maxLength: 256
          description: Tag name.
          example: campaign
        value:
          type: string
          maxLength: 256
          description: Tag value.
          example: welcome
    Attachment:
      type: object
      required:
        - filename
        - content
      properties:
        filename:
          type: string
          maxLength: 255
          description: Name of the file.
          example: invoice.pdf
        content:
          type: string
          description: Base64-encoded file content.
          example: JVBERi0xLjQKJeLj...
        content_type:
          type: string
          maxLength: 255
          description: >-
            MIME type of the file. If not provided, it will be inferred from the
            filename.
          example: application/pdf
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Invalid API key.
    ValidationError:
      description: Validation error — invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: The email field is required.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key from your SendKit dashboard. Pass it as a Bearer token in the
        Authorization header.

````