Set up your email sender domain

Overview

Use this once when setting up white-label email.

You'll need the domain.

Returns the DNS records to add. Once they're in place, emails send from your domain. If this sender (same email and tracking_domain) is already fully verified, only its name is updated and you get status: already_verified with an empty data.

Prerequisites

A bearer token. See Authentication.
The account's id (company_id).
A sender address on a domain you control, and a tracking subdomain on it.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/account/white-label/email/add

Authentication

Partner or Account token

company_id must be inside your own account tree. A Partner token can use any account under the partner; an Account token only its own account.
An account outside your tree, or one that doesn't exist, is rejected with 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`company_id`	integer	Yes	The account. Must exist and be inside your account tree.
`sender_name`	string	Yes	The name emails come from. Up to 100 characters, no angle brackets.
`email`	string	Yes	The sender address. Must be a valid address on a domain that exists in DNS; the domain is checked with our email provider.
`tracking_domain`	string	Yes	The domain used for link tracking, e.g. `track.acme.com`. Up to 100 characters, no angle brackets.

Request payload

{
  "company_id": 5994,
  "sender_name": "Acme Reviews",
  "email": "[email protected]",
  "tracking_domain": "track.acme.com"
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success` (sender saved), or `already_verified` (it was already fully verified; only the name was updated).
`data`	object or array	The saved sender, or an empty array `[]` when `already_verified`.
`data.id`	integer	The sender record's id.
`data.company_id`	integer	The account.
`data.email`	string	The sender address.
`data.name`	string	The sender name.
`data.domain`	string	The sender address's domain.
`data.tracking_url`	string	The tracking domain.
`data.domain_verified_at`	string or null	When the sending domain was verified; `null` until then.
`data.url_verified_at`	string or null	When the tracking domain was verified; `null` until then.
`data.created_at`	string	When the sender was added (ISO 8601).
`data.updated_at`	string	When it was last changed (ISO 8601).
`verification`	object	The verification checks. Absent when `already_verified`.
`verification.verify_domain`	object or array	The email provider's domain verification result (e.g. `status`: `already_verified`). An empty array `[]` when no sender is set up.
`verification.check_domain`	object or array	The email provider's DNS check for the sending domain (`spf`, `dkim`, `dkim2`, `dmarc`, `valid_signing`, ...). `[]` when no sender is set up.
`verification.check_tracking_domain`	object or array	The email provider's check of the tracking domain (`cname`, `valid_tracking`, ...). `[]` when no sender is set up.
`verification.default_settings`	object	The platform sender used until yours is verified.
`verification.default_settings.email`	string	Default sender address.
`verification.default_settings.name`	string	Default sender name.
`verification.default_settings.tracking_url`	string	Default tracking domain.

Response payload

{
  "data": {
    "status": "success",
    "data": {
      "company_id": 5994,
      "email": "[email protected]",
      "tracking_url": "track.manage-myreviews.com",
      "domain": "manage-myreviews.com",
      "name": "Acme Reviews",
      "domain_verified_at": "2026-06-23 10:00:00",
      "url_verified_at": "2026-06-23 10:00:00",
      "updated_at": "2026-06-23T10:00:00.000000Z",
      "created_at": "2026-06-23T10:00:00.000000Z",
      "id": 1
    },
    "verification": {
      "verify_domain": {
        "status": "already_verified",
        "domain": "manage-myreviews.com",
        "email": "[email protected]"
      },
      "check_domain": {
        "domain": "manage-myreviews.com",
        "dkim": {
          "valid": true
        },
        "dkim2": {
          "valid": true
        },
        "dmarc": {
          "valid": true
        },
        "valid_signing": true
      },
      "check_tracking_domain": {
        "domain": "track.manage-myreviews.com",
        "cname": {
          "valid": true
        }
      },
      "default_settings": {
        "email": "[email protected]",
        "name": "Shout About Us",
        "tracking_url": "track.shoutaboutus.com"
      }
    }
  }
}

Examples

Success payload

Saved: see Response payload.

The sender was already fully verified:

{
  "data": {
    "status": "already_verified",
    "data": []
  }
}

Error payload

400 Invalid domain

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "status": "error",
    "message": "Invalid Domain"
  }
}

422 Required fields missing

{
  "message": "The sender name field is required. (and 2 more errors)",
  "errors": {
    "sender_name": [
      "The sender name field is required."
    ],
    "email": [
      "The email field is required."
    ],
    "tracking_domain": [
      "The tracking domain field is required."
    ]
  }
}

422 email isn't valid

{
  "message": "The email field must be a valid email address.",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ]
  }
}

422 Account outside your tree

{
  "message": "The selected company id does not belong to your company hierarchy.",
  "errors": {
    "company_id": [
      "The selected company id does not belong to your company hierarchy."
    ]
  }
}

Status	Meaning
`200`	The sender was saved, or it was already verified.
`400`	Our email provider rejected the sender's domain.
`401`	The token is missing, expired or invalid.
`422`	A required field is missing, `email` isn't a valid address on a real domain, or `company_id` doesn't exist or is outside your tree.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/white-label/email/add" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"company_id": 5994, "sender_name": "Acme Reviews", "email": "[email protected]", "tracking_domain": "track.acme.com"}'