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

# Add a Sender

> Add a sender (from address) on a **verified** domain — the same as **Add sender** in **Account Settings → Senders**. A sender on a verified domain is verified at once (no confirmation email).

The address fields are optional; any you leave out are taken from your account profile. They are shown on the sender's details only and are not used for sending.



## OpenAPI

````yaml /openapi-v1.json post /senders
openapi: 3.1.0
info:
  title: Mailercloud Marketing API
  version: 1.0.0
  description: >-
    Campaigns, contacts, lists, segments, automations, and webhooks for the
    Mailercloud Marketing Platform.
servers:
  - url: https://cloudapi.mailercloud.com/v1
security:
  - apiKey: []
tags:
  - name: Campaigns
  - name: Contacts
  - name: Lists
  - name: Tags
  - name: Segments
  - name: Custom Properties
  - name: Senders
  - name: Domains
  - name: Templates
  - name: Automations
  - name: Webhooks
  - name: Webforms
  - name: Inbox Tracker
  - name: Account
paths:
  /senders:
    post:
      tags:
        - Senders
      summary: Add a Sender
      description: >-
        Add a sender (from address) on a **verified** domain — the same as **Add
        sender** in **Account Settings → Senders**. A sender on a verified
        domain is verified at once (no confirmation email).


        The address fields are optional; any you leave out are taken from your
        account profile. They are shown on the sender's details only and are not
        used for sending.
      operationId: add-a-sender
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sender_email
                - sender_name
              properties:
                sender_email:
                  type: string
                  format: email
                  description: >-
                    The from address. Its domain must be added and verified in
                    your account.


                    Minimum: 5

                    Maximum: 100
                sender_name:
                  type: string
                  description: >-
                    The from name.


                    Maximum: 100


                    Plain text (ASCII); `<`, `>`, `@`, `"` and line breaks are
                    not allowed.
                company_address:
                  type: string
                  description: |-
                    Company address.

                    Minimum: 3
                    Maximum: 500
                city:
                  type: string
                  description: |-
                    City.

                    Minimum: 3
                    Maximum: 100
                state:
                  type: string
                  description: |-
                    State.

                    Minimum: 3
                    Maximum: 100
                zip_code:
                  type: string
                  description: |-
                    ZIP / postal code.

                    Minimum: 4
                    Maximum: 15
                country:
                  type: string
                  description: Country name or ISO code, e.g. `India`, `IN` or `IND`.
            examples:
              Name and email:
                value:
                  sender_email: news@example.com
                  sender_name: Example News
              With address:
                value:
                  sender_email: news@example.com
                  sender_name: Example News
                  company_address: 12 Market Street
                  city: Chennai
                  state: Tamil Nadu
                  zip_code: '600001'
                  country: India
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Sender ID
                  sender_email:
                    type: string
                  sender_name:
                    type: string
                  status:
                    type: string
                    enum:
                      - verified
                    description: Always `verified` (the domain is verified)
              examples:
                Example-1:
                  value:
                    id: ZZaSxx
                    sender_email: news@example.com
                    sender_name: Example News
                    status: verified
        '400':
          description: >-
            Bad Request — invalid input or the sender was refused (same messages
            as the app)
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
              examples:
                Domain not verified:
                  value:
                    errors:
                      - field: sender_email
                        message: You must verify the domain 'example.com'.
                Already exists:
                  value:
                    errors:
                      - field: sender_email
                        message: Sender already exists
                Invalid email:
                  value:
                    errors:
                      - field: sender_email
                        message: This value is not a valid email address.
                Unicode name:
                  value:
                    errors:
                      - field: sender_name
                        message: Sender name cannot contain unicode characters
                Unknown country:
                  value:
                    errors:
                      - field: country
                        message: Country not found
                Invalid JSON:
                  value:
                    errors:
                      - field: ''
                        message: Invalid json format
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
              examples:
                Example-1:
                  value:
                    errors:
                      - field: ''
                        message: Authorization failed
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Example-1:
                  value:
                    message: Too Many Requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Example-1:
                  value:
                    message: >-
                      Sorry, we are experiencing some technical difficulties.
                      Please try after some time.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your Mailercloud API key (plain text, no Bearer prefix). Create keys in
        Settings → API.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.