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

# Send Email Using Template

> Send an email using a template from your library. Requires a verified custom domain or valid 'from' field.



## OpenAPI

````yaml api-reference/openapi.json post /send
openapi: 3.0.3
info:
  title: Senderr Email Template API
  description: >-
    API for accessing and managing email templates in your library. Supports
    both session-based authentication and API key authentication with rate
    limiting based on subscription plans.
  version: 1.0.0
  contact:
    name: Senderr Support
    url: https://senderr.dev/contact
    email: support@senderr.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://senderr.dev/terms
servers:
  - url: https://senderr.dev/api/v1
    description: Production server
  - url: http://localhost:3000/api/v1
    description: Development server
security:
  - BearerAuth: []
  - SessionAuth: []
tags:
  - name: Library
    description: Operations related to user's template library
  - name: Templates
    description: Operations for template rendering and source code access
  - name: Email
    description: Operations for sending emails using templates
  - name: Usage
    description: Operations for checking API usage and limits
paths:
  /send:
    post:
      tags:
        - Email
      summary: Send Email Using Template
      description: >-
        Send an email using a template from your library. Requires a verified
        custom domain or valid 'from' field.
      operationId: sendEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailSendRequest'
            example:
              template_id: 550e8400-e29b-41d4-a716-446655440000
              to:
                - recipient@example.com
              subject: Welcome to our platform!
              variables:
                name: John Doe
                company: Acme Corp
              from: sender@yourcompany.com
              reply_to: support@yourcompany.com
      responses:
        '200':
          description: Email sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailSendResponse'
              example:
                success: true
                data:
                  id: re_01H123ABC...
                  from: sender@yourcompany.com
                  to:
                    - recipient@example.com
                  subject: Welcome to our platform!
                  sent_at: '2024-01-01T12:00:00Z'
                meta:
                  email_usage:
                    monthly_limit: 1000
                    current_usage: 45
                    remaining: 955
                    plan_type: monthly
                    is_overage: false
                    overage_emails: 0
                    stripe_usage_reported: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Template not found in library
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Template not found
                message: >-
                  This template is not in your library. Please purchase the
                  template first to use it for sending emails.
                success: false
        '429':
          description: Rate limit or email sending limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Email sending not allowed
                  message:
                    type: string
                    example: You have reached your monthly email sending limit
                  is_overage:
                    type: boolean
                    description: Whether the user is in overage mode
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl -X POST https://senderr.dev/api/v1/send \
              -H "Content-Type: application/json" \
              -H "X-API-Key: your-api-key" \
              -d '{
                "template_id": "550e8400-e29b-41d4-a716-446655440000",
                "to": ["recipient@example.com"],
                "subject": "Welcome!",
                "variables": {
                  "name": "John Doe"
                }
              }'
        - lang: javascript
          label: JavaScript/Node.js
          source: |-
            const response = await fetch('https://senderr.dev/api/v1/send', {
              method: 'POST',
              headers: {
                'Content-Type': 'application/json',
                'X-API-Key': 'your-api-key'
              },
              body: JSON.stringify({
                template_id: '550e8400-e29b-41d4-a716-446655440000',
                to: ['recipient@example.com'],
                subject: 'Welcome!',
                variables: {
                  name: 'John Doe'
                }
              })
            });

            const result = await response.json();
            console.log(result);
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.post(
                'https://senderr.dev/api/v1/send',
                headers={
                    'Content-Type': 'application/json',
                    'X-API-Key': 'your-api-key'
                },
                json={
                    'template_id': '550e8400-e29b-41d4-a716-446655440000',
                    'to': ['recipient@example.com'],
                    'subject': 'Welcome!',
                    'variables': {
                        'name': 'John Doe'
                    }
                }
            )

            result = response.json()
            print(result)
components:
  schemas:
    EmailSendRequest:
      type: object
      properties:
        template_id:
          type: string
          format: uuid
          description: ID of the template to use for sending the email
        to:
          oneOf:
            - type: string
              format: email
            - type: array
              items:
                type: string
                format: email
          description: Recipient email address(es)
        cc:
          oneOf:
            - type: string
              format: email
            - type: array
              items:
                type: string
                format: email
          description: CC email address(es)
        bcc:
          oneOf:
            - type: string
              format: email
            - type: array
              items:
                type: string
                format: email
          description: BCC email address(es)
        reply_to:
          oneOf:
            - type: string
              format: email
            - type: array
              items:
                type: string
                format: email
          description: Reply-to email address(es)
        from:
          type: string
          description: >-
            Sender email address. Can be 'email@domain.com' or 'Name
            <email@domain.com>' format. If not provided, uses your verified
            domain.
        subject:
          type: string
          description: Email subject line
        variables:
          type: object
          additionalProperties: true
          description: Variables to use when rendering the template
          default: {}
        text:
          type: string
          description: Plain text version of the email (optional)
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom headers for the email
        attachments:
          type: array
          items:
            type: object
            properties:
              filename:
                type: string
              content:
                type: string
                description: Base64 encoded content
              content_type:
                type: string
              path:
                type: string
                description: File path (alternative to content)
          description: Email attachments
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                maxLength: 256
              value:
                type: string
                maxLength: 256
            required:
              - name
              - value
          description: Email tags for tracking and organization
        scheduled_at:
          type: string
          format: date-time
          description: Schedule email for future delivery (ISO 8601 format)
      required:
        - template_id
        - to
        - subject
    EmailSendResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            id:
              type: string
              description: Email provider's unique identifier for the sent email
            from:
              type: string
              format: email
              description: Sender email address used
            to:
              type: array
              items:
                type: string
                format: email
              description: Recipient email addresses
            subject:
              type: string
              description: Email subject line
            sent_at:
              type: string
              format: date-time
              description: When the email was sent
        meta:
          type: object
          properties:
            email_usage:
              type: object
              properties:
                monthly_limit:
                  type: integer
                  description: Monthly email sending limit
                current_usage:
                  type: integer
                  description: Current emails sent this month
                remaining:
                  type: integer
                  description: Remaining emails for this month
                plan_type:
                  type: string
                  enum:
                    - free
                    - monthly
                    - annual
                  description: Current subscription plan
                is_overage:
                  type: boolean
                  description: Whether user is in overage mode
                overage_emails:
                  type: integer
                  description: Number of overage emails sent
                stripe_usage_reported:
                  type: boolean
                  description: Whether usage was reported to Stripe for billing
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
        success:
          type: boolean
          example: false
        details:
          type: object
          description: Additional error details
      required:
        - error
        - success
    ValidationErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
  responses:
    BadRequest:
      description: Bad request - invalid input data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
          example:
            error: Invalid request body
            code: VALIDATION_ERROR
            success: false
            details:
              - field: variables
                message: Variables must be an object
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Authentication required
            success: false
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Internal server error
            code: INTERNAL_ERROR
            success: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Use your API key from the dashboard. Format: `Bearer your-api-key-here`'
    SessionAuth:
      type: apiKey
      in: cookie
      name: supabase-auth-token
      description: Session-based authentication using browser cookies

````