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

# Provision New Sender

> Initiate DNS/Email verification for a new identity.

### Request Body

<ParamField body="name" type="string" required>
  Internal label for the sender
</ParamField>

<ParamField body="email" type="string" required>
  The 'from' email address
</ParamField>

<ParamField body="provider" type="string" required>
  Provider type (stalwart, gmail\_oauth)
</ParamField>

<ParamField body="from_name" type="string">
  Display name in recipients' inbox
</ParamField>

<ParamField body="reply_to_email" type="string">
  Address for replies
</ParamField>

<ParamField body="verified_domain_id" type="string">
  Required for 'stalwart' provider
</ParamField>

<RequestExample>
  ```json Request theme={null}
  {
    "name": "Global Support Desk",
    "email": "support@yourdomain.com",
    "provider": "stalwart",
    "from_name": "Syntr Support",
    "reply_to_email": "tickets@yourdomain.com",
    "verified_domain_id": "b7e1-9283-acde-4912-8839"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "b7e1-acde",
      "tracking_id": "verify_seq_8872"
    }
  }
  ```
</ResponseExample>

### Connection Guide

Different providers follow distinct setup flows. Follow the instructions below depending on your provider choice:

<Tabs>
  <Tab title="Stalwart Mail">
    Stalwart senders are provisioned directly using this POST endpoint.

    1. First, add and verify your custom domain in the Domain Setup interface (DNS verification).
    2. Retrieve the `verified_domain_id` (UUID) for your verified domain.
    3. Make a `POST` request to `/sender-emails` with:
       * `provider`: `"stalwart"`
       * `verified_domain_id`: The domain UUID.
       * `email`: The desired email address matching the domain (e.g. `support@yourdomain.com`).
  </Tab>

  <Tab title="Gmail Workspace (OAuth)">
    Gmail Workspace senders **cannot** be provisioned directly via this POST endpoint. Instead, they must be connected using the web-based Google OAuth flow:

    1. Initiate the OAuth flow by redirecting the user to:
       ```http theme={null}
       GET /api/v1/auth/google/gmail?returnUrl={YOUR_DASHBOARD_URL}
       ```
    2. Once the user completes Google Workspace authentication, Google redirects back to the platform callback, which automatically registers/creates the sender email with `provider`: `"gmail_oauth"`.
  </Tab>
</Tabs>