> ## 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. # Create a draft, send, or schedule a newsletter > Creates a newsletter from content and a server-resolved audience or legacy email list. Requires nonempty selected email addresses even for a draft. status=sent becomes sending and queues durable recipient deliveries; suppression, marketing preferences, deduplication and current donor addresses are checked. Audiences over500 defer eligibility and report nullable counts. Scheduling resolves exact time at least five minutes ahead, matches any legacy fields, verifies current recommendations and permits at most10 scheduled newsletters. Draft save returns200; scheduled creation returns201. A queue receipt does not promise inbox delivery. Requires permission: one of newsletter. ## OpenAPI ````yaml post /admin/send/newsLetter 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/send/newsLetter: post: tags: - Communications summary: Create a draft, send, or schedule a newsletter description: >- Creates a newsletter from content and a server-resolved audience or legacy email list. Requires nonempty selected email addresses even for a draft. status=sent becomes sending and queues durable recipient deliveries; suppression, marketing preferences, deduplication and current donor addresses are checked. Audiences over500 defer eligibility and report nullable counts. Scheduling resolves exact time at least five minutes ahead, matches any legacy fields, verifies current recommendations and permits at most10 scheduled newsletters. Draft save returns200; scheduled creation returns201. A queue receipt does not promise inbox delivery. Requires permission: one of newsletter. operationId: communicationsNewsletterPostSendNewsletter requestBody: description: Validated request fields for this operation. required: true content: application/json: schema: required: - from - message - title - status properties: from: description: >- Recorded actor/sender email; actual delivery uses organization email settings. type: string format: email example: admin@example.org message: description: >- Newsletter HTML; saved Impact Story evidence is checked when present. type: string example:

Thank you for supporting education.

title: type: string example: Education field update status: type: string enum: - draft - sent - scheduled example: draft to: description: >- Legacy/manual donor ids; selects server-owned current addresses when audience intent is present. type: array items: description: Organization-owned record identifier. type: integer example: 42 nullable: false nullable: true emails: description: >- Explicit email audience only when no server-resolved audience intent is supplied. type: array items: type: string format: email example: jane@example.org nullable: true tag: description: >- Legacy comma-separated tag selection; tags/audience_selection take priority. type: string example: Education nullable: true tags: type: array items: type: string example: Education nullable: true audience_selection: description: >- Server-resolved audience intent. all snapshots all active donors with nonblank email; static unions current ANY-tag matches with additions minus exclusions; manual uses individual ids. Unknown/non-tenant/no-email ids are omitted. properties: mode: type: string enum: - all - manual - static - null example: static nullable: true tags: type: array items: type: string example: Education nullable: true individual_donor_ids: type: array items: description: Organization-owned record identifier. type: integer example: 42 nullable: false nullable: true excluded_tag_donor_ids: type: array items: description: Organization-owned record identifier. type: integer example: 42 nullable: false nullable: true type: object nullable: true select_all_donors: description: Overrides other selection fields with an all-donor snapshot. type: boolean example: false nullable: true design: description: >- Editor design object or serialized string; persisted as text. nullable: true attachment: description: >- Existing attachment reference; no multipart upload is performed. type: string example: https://example.org/newsletter.pdf nullable: true fileName: description: Legacy attachment alias; attachment takes priority. type: string example: https://example.org/newsletter.pdf nullable: true scheduled_at: description: >- Legacy local/offset date-time; required for scheduling unless schedule is provided. Must be at least five minutes ahead. type: string example: '2026-10-27T15:00:00' nullable: true timezone: description: >- IANA timezone; otherwise stored/account/admin timezone fallback. type: string maxLength: 64 example: Africa/Kampala nullable: true schedule: $ref: '#/components/schemas/CommunicationsNewsletterSchedule' type: object responses: '200': description: Operation result. content: application/json: schema: $ref: '#/components/schemas/CommunicationsNewsletterSendReceipt' '201': description: Scheduled newsletter created. content: application/json: schema: $ref: '#/components/schemas/CommunicationsNewsletterSendReceipt' '400': description: The organization already has10 scheduled newsletters. '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. '422': description: >- Validation, selected recipients, schedule or current story evidence is invalid. content: application/json: schema: $ref: '#/components/schemas/RequestRejection' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: CommunicationsNewsletterSchedule: required: - kind - localDatetime - timezone - offsetMinutes - utcAt - source properties: kind: type: string enum: - instant example: instant localDatetime: description: Confirmed local wall time without timezone suffix. type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$ example: '2026-10-27T15:00:00' timezone: description: IANA timezone; must match utcAt and offsetMinutes. type: string example: Africa/Kampala offsetMinutes: description: UTC offset in minutes at the selected instant. type: integer example: 180 utcAt: description: >- Matching ISO8601 UTC instant with Z suffix; at least five minutes ahead. type: string format: date-time example: '2026-10-27T12:00:00Z' source: type: string enum: - calendar - natural_language - preset - recommendation - legacy example: calendar recommendationId: description: >- Required only for recommendation; must reference a current ready recommendation matching time/timezone. type: string example: 550e8400-e29b-41d4-a716-446655440000 type: object additionalProperties: false CommunicationsNewsletterSendReceipt: description: >- Send/approve/retry receipt; id/title/schedule fields depend on operation. Successful queueing does not prove provider acceptance or inbox delivery. properties: message: type: string example: News letter is being sent status: type: string enum: - draft - scheduled - sending - sent - failed - skipped example: sending id: description: Organization-owned record identifier. type: integer example: 42 nullable: false title: type: string example: Education field update scheduled_at: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true timezone: type: string example: Africa/Kampala nullable: true scheduled_timezone: type: string example: Africa/Kampala nullable: true schedule_source: type: string example: calendar nullable: true recipient_count: description: Count. type: integer minimum: 0 example: 1 eligible_recipient_count: description: Null while eligibility is deferred for audiences larger than500. type: integer minimum: 0 example: 1 nullable: true suppressed_recipient_count: description: Null while eligibility is deferred for audiences larger than500. type: integer minimum: 0 example: 0 nullable: true recipient_eligibility_pending: description: Present and true only when eligibility is deferred. type: boolean example: true 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 RequestRejection: description: >- Request or workflow rejection. Framework field-validation failures contain errors; semantic rejections may contain message without errors; legacy/provider failures may use error and error_code. The operation description identifies the rejected condition. Domain responses may add current revision, limits or other conflict context. anyOf: - $ref: '#/components/schemas/ValidationErrorResponse' - $ref: '#/components/schemas/ErrorResponse' - required: - error properties: error: description: Legacy or provider-facing error message. type: string example: The request could not be completed. error_code: description: Stable domain error code, when provided. type: string example: WORKFLOW_UNAVAILABLE 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 ErrorResponse: title: ErrorResponse description: >- Generic error envelope used by most controllers. Most error responses pair a human-readable `message` with `status: error`. Some endpoints additionally include `errors` (validator errors), `error` (legacy single-error string), `code`, or domain-specific context fields. required: - message properties: message: description: Human-readable error message. type: string example: Something went wrong. Please try again. status: description: >- Always the literal string `error` for failures. Some endpoints omit this field. type: string example: error error: description: Legacy single error code/string used by older endpoints. type: string example: invalid_request nullable: true code: description: >- Optional application-level error code (not all endpoints populate this). type: string example: DONOR_NOT_FOUND 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.