---
title: "Send a facility credentialing outreach email"
method: POST
path: "/facility-credentialing-outreaches"
tags: ["Facility Credentialing Outreach Resource"]
---

# Send a facility credentialing outreach email

`POST /facility-credentialing-outreaches`

Triggers a credentialing outreach email for a facility credentialing workflow by dispatching it through SendGrid and persisting a new outreach record. This operation is not idempotent - every call sends another email and creates another outreach record. Call it after the target facility credentialing workflow already exists. For a single-workflow outreach, supply workflowId. For a multi-tenant outreach that fans out to two or more recipient workflows, supply workflowIds (two or more entries) together with initiatingWorkflowId, which must be one of the entries in workflowIds; workflowId and workflowIds are mutually exclusive. Any file attachments must already be uploaded to Google Cloud Storage before calling this endpoint - the request only references them by metadata. For multi-workflow requests only, the initiating tenant (identified by the tenant-id header) must have a fully configured outreach-settings template (subject and body) for the relevant credentialing cycle, or the request is rejected with 422; single-workflow requests do not perform this template check. Multi-workflow requests also require the OUTREACH_MULTI_TENANT_ENABLED feature flag to be enabled, or they are rejected with 503; single-workflow requests are unaffected by this flag.

## Headers

- `tenant-id` string, required

## Request body

- SendCredentialingOutreachRequest — Request body for sending a credentialing outreach email
  - `workflowId` string — The workflow ID for the credentialing outreach. Required for single-workflow requests. When workflowIds is provided with more than one entry, this field is optional.
  - `workflowIds` string[] — List of workflow IDs for multi-tenant outreach. When more than one entry is provided, initiatingWorkflowId must also be set. Single-workflow requests should leave this null and use workflowId instead.
  - `initiatingWorkflowId` string — The workflow ID of the initiating org for multi-tenant outreach. Required when workflowIds contains more than one entry. Must be present in the workflowIds list. The initiating workflow's tenant outreach-settings template is applied to all bundled workflows.
  - `toEmails` string[], required — List of email addresses to send the outreach email to
  - `body` string, required — Email body content
  - `ccEmails` string[] — Optional list of CC email addresses
  - `bccEmails` string[] — Optional list of BCC email addresses
  - `outreachReasons` string[], required — List of reasons for the outreach
  - `outreachReasonsWithLabels` OutreachReasonWithLabel[] — List of outreach reasons with their display labels. When provided, labels are persisted with the outreach record.
    - `id` string — Unique identifier for the outreach reason
    - `label` string — Display label for the outreach reason
  - `subject` string, required — Email subject line
  - `attachments` AttachmentDTO[] — Optional list of email attachments
    - `filename` string, required
    - `content` string, binary, required
    - `contentType` string, required
  - `multiTenant` boolean

## Response `201`

The outreach email was sent and a new outreach record was created. A single-workflow request returns a bare JSON string containing the new outreach record ID. A multi-workflow request returns an object with outreachId (the single outreach record shared by all bundled workflows) and sends (one entry per workflow with workflowId, tenantId, emailId, status of SENT or FAILED, sendgridId, and errorMessage - the last three are null on whichever branch did not occur).

## Other responses

- `400` — Three distinct 400 shapes are possible. (1) Bean Validation failed on the request body - toEmails, subject, or body was missing or blank; this returns the structured ApiError shape shown in the validationError example. (2) workflowId was omitted and workflowIds does not contain more than one entry, so neither the single-workflow nor multi-workflow path applies; this returns the missingWorkflowId example. (3) initiatingWorkflowId is missing or is not a member of workflowIds on a multi-workflow request; this returns the invalidInitiatingWorkflowId example.
- `401` — The request has no valid authentication token.
- `403` — The caller lacks the credentialing-outreach:create permission required to send facility outreach.
- `422` — Multi-workflow requests only: the initiating tenant's outreach-settings template has no configured subject/body for the outreach type and credentialing cycle being sent. Configure the template for that tenant before retrying; single-workflow requests never return this status.
- `500` — An unexpected error occurred while sending the outreach.
- `503` — Two distinct causes return 503. (1) A multi-workflow request was made while the OUTREACH_MULTI_TENANT_ENABLED feature flag is disabled in this environment; see the multiTenantDisabled example. (2) The underlying data service was temporarily unavailable while sending the outreach on either path; see the serviceUnavailable example and retry the request.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)