> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.helpyousponsor.com/llms.txt > Use this file to discover all available pages before exploring further. # Start verified email domain setup > Derives the base domain from the organization saved From address and creates the prefix subdomain, default mg with us region. Public mailbox domains are rejected. Setup is idempotent for the same subdomain; a normal receipt returns 201 even when reusing an existing setup. Add the returned sending DNS records, then check verification. An ambiguous provider outcome returns 202 with code/data and can reconcile later; existing externally claimed domains return 409 with a suggested prefix. Existing active/ready setup must be removed before changing prefixes. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email. ## OpenAPI ````yaml post /admin/email/settings/sending-domains openapi: 3.0.0 info: title: Gratona API description: >- REST API for the Gratona fundraising platform, including donor, donation, sponsorship, program, event, and integration workflows. Endpoints are organized by tag. Most endpoints require either a Passport bearer token or an issued API key — see the Security Schemes section. contact: name: Gratona Engineering url: https://gratona.com email: devs@gratona.com version: 1.0.0 servers: - url: https://api.gratona.com/v1 description: Server Version 1.0.0 security: [] tags: - name: Auth description: >- Login, signup, logout, password reset, and email verification for admin users and donors. - name: Donors description: >- Donor records: CRUD, profile fields, household linkage, search, filters, merge, and duplicate detection. - name: Donations description: >- Individual donation records, recurring commitments, soft credits, refunds, designations, and exports. - name: Sponsorships description: >- Donor-to-entity commitment relationships, lifecycle transitions, and commitment-specific filters. - name: Entities description: >- Recipient records (children, families, projects, animals, etc.), their status, and entity-level fields. - name: Programs description: >- Program / campaign configuration: hierarchy, settings, and program-level metadata. - name: Forms description: >- Custom form builder (HysForm), form fields, standardized donor fields, and field migrations. - name: Trips description: >- Mission-trip management: trips, participants, budgets, tasks, e-signatures, fundraising milestones, and background checks. - name: Communications description: >- Email templates, SMS, newsletters, donor email manager, and per-donor notes. - name: Payments description: >- Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks). Excludes inbound webhooks — see the Webhooks tag. - name: Reports description: Dashboards, analytics, scheduled reports, and exports. - name: Admin description: >- Client-account administration: users, groups/permissions, settings, integrations, and account lifecycle. - name: Donor Portal description: >- Endpoints consumed by the donor-facing portal (donor login, dashboard, donation history, messages). - name: Recipient Portal description: Endpoints consumed by the recipient-facing portal. - name: Public description: >- Unauthenticated public endpoints: donor signup, public trip pages, peer-to-peer campaigns, public checkout. - name: Webhooks description: >- Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr, DropboxSign). Annotated minimally for reference; payload shapes are owned by the upstream provider. - name: Events description: >- Event setup, invitations, registration, ticketing, attendance and event reporting. - name: Journeys description: >- Journey graphs, activation, enrollment, message templates and event follow-up automations. - name: Tasks description: Workspace tasks, assignments, saved task views and record collaboration. - name: Fundraising description: >- Fundraising portfolios, stewardship plans, giving anniversaries and personal donor follow-up. - name: Impact Stories description: Story intake, review, assets, consent and publication workflows. - name: Integrations description: Workspace integration connections, mappings, synchronization and recovery. - name: Email Calendar description: Connected email/calendar accounts and donor interactions. - name: Spaces description: Workspace Spaces and collaborative Pages. - name: Library description: Workspace documents, source connections, files and analysis. - name: Intelligence description: Donor intelligence and Tali workspace workflows. - name: Automation description: >- V3 automation primitive discovery, input validation, invocation and Zapier contracts. - name: Schema description: V3 model, enum, capability and scope discovery. - name: Zapier description: Zapier automation connections, polling feeds and actions. - name: Files description: Files - name: Client description: Client - name: Payment Gateways description: Payment Gateways - name: Email Settings description: Email Settings - name: Admin Dashboard description: Admin Dashboard - name: Recipients description: Recipients - name: Historical Archived Updates description: Historical Archived Updates - name: Team & access description: Team & access - name: Settings description: Settings - name: Notifications description: Notifications - name: Participation description: Participation - name: Users description: Users - name: Wrapped description: Wrapped - name: Donor SignUp description: Donor SignUp - name: Frontend description: Frontend - name: User description: User - name: Workspace description: Workspace paths: /admin/email/settings/sending-domains: post: tags: - Communications summary: Start verified email domain setup description: >- Derives the base domain from the organization saved From address and creates the prefix subdomain, default mg with us region. Public mailbox domains are rejected. Setup is idempotent for the same subdomain; a normal receipt returns 201 even when reusing an existing setup. Add the returned sending DNS records, then check verification. An ambiguous provider outcome returns 202 with code/data and can reconcile later; existing externally claimed domains return 409 with a suggested prefix. Existing active/ready setup must be removed before changing prefixes. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email. operationId: communicationsEmailSendingDomainStore requestBody: description: Validated request fields for this operation. required: false content: application/json: schema: properties: region: type: string default: us enum: - us - eu example: us prefix: description: >- One subdomain label; trimmed and lowercased. Letters, digits and internal hyphens only. type: string default: mg maxLength: 63 minLength: 1 pattern: ^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$ example: mg type: object responses: '201': description: Operation result. content: application/json: schema: properties: message: type: string data: $ref: '#/components/schemas/CommunicationsSendingDomain' type: object '202': description: >- Provisioning outcome is uncertain; inspect code/data and reconcile instead of assuming completion. content: application/json: schema: $ref: '#/components/schemas/CommunicationsSendingDomainError' '401': description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '403': description: >- The authenticated user lacks access to this workflow or its related records. '409': description: Provisioning is in progress or the subdomain is claimed/conflicted. content: application/json: schema: $ref: '#/components/schemas/CommunicationsSendingDomainError' '422': description: >- Invalid prefix/From domain, or a ready/active setup prevents changing the subdomain. content: application/json: schema: oneOf: - $ref: '#/components/schemas/CommunicationsSendingDomainError' - $ref: '#/components/schemas/ValidationErrorResponse' '502': description: Provider lookup or provisioning failed. content: application/json: schema: $ref: '#/components/schemas/CommunicationsSendingDomainError' '503': description: Domain authentication is not configured. content: application/json: schema: $ref: '#/components/schemas/CommunicationsSendingDomainError' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: CommunicationsSendingDomain: description: >- Safe domain verification/delivery state. Credentials, provider account ids and transport snapshots are not returned. active alone does not guarantee transport_ready. properties: id: description: Organization-owned record identifier. type: integer example: 42 domain: type: string example: mg.example.org from_domain: type: string example: example.org region: type: string enum: - us - eu example: us status: type: string enum: - pending_dns - verified - active - degraded example: pending_dns provisioning_status: type: string enum: - checking - creating - ready - external_conflict - outcome_unknown - failed example: ready suggested_prefix: type: string example: send nullable: true provider_state: type: string example: unverified nullable: true active: type: boolean example: true dns_records: description: >- Only TXT/CNAME sending records at or below this sending subdomain; receive/MX records are excluded. type: array items: properties: type: type: string enum: - TXT - CNAME example: TXT name: type: string example: mg.example.org value: type: string example: v=spf1 include:mailgun.org ~all priority: type: string nullable: true valid: type: boolean example: true validity: type: string example: valid type: object last_error: type: string nullable: true last_error_code: type: string nullable: true next_reconcile_at: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true last_checked_at: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true verified_at: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true tested_at: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true activated_at: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true transport_ready: type: boolean example: true other_domain_senders: properties: items: type: array items: properties: id: description: Organization-owned record identifier. type: integer example: 42 name: type: string example: Education updates from: type: string format: email example: updates@other.example.org type: object maxItems: 10 total: type: integer example: 1 type: object type: object CommunicationsSendingDomainError: description: >- Service error/accepted-reconciliation receipt. message/code are present; data and suggested_prefix appear only for applicable provisioning states. required: - message - code properties: message: type: string example: Finish DNS verification before activating verified sending. code: type: string example: domain_not_verified data: $ref: '#/components/schemas/CommunicationsSendingDomain' suggested_prefix: type: string example: send type: object UnauthorizedResponse: title: UnauthorizedResponse description: >- Returned with HTTP 401 when the request lacks a valid Passport bearer token, a valid `X-HYS-API-Key`, or a valid session. The body is the simple `{message, status}` envelope emitted by `AuthenticateApiOrKey`. required: - message - status properties: message: description: >- Always the literal string `Unauthorized` from the `auth.api_or_key` middleware. Login endpoints return `Invalid Credentials` instead. type: string example: Unauthorized status: type: string example: error type: object ValidationErrorResponse: title: ValidationErrorResponse description: >- Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The `errors` map is keyed by the failing field name; each value is an array of human-readable error messages for that field. Most controllers also include a top-level `status: error`. required: - errors properties: errors: description: >- Map of field name to array of validator error messages. Example: `{email: [The email field is required.], amount: [The amount must be a number.]}`. type: object additionalProperties: type: array items: type: string status: description: Always the literal string `error`. type: string example: error message: description: >- Optional summary message — present on some endpoints, absent on others. type: string example: The given data was invalid. nullable: true type: object securitySchemes: bearerAuth: type: http description: Passport bearer token authentication for legacy admin sessions. scheme: bearer bearerFormat: JWT apiKeyAuth: type: apiKey description: Gratona API key sent with the compatibility header X-HYS-API-Key. name: X-HYS-API-Key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.