Documentation version: 2026-09-18.3
Canonical: https://docs.creator.gg/tools/email_campaigns_schedule.md

# email_campaigns_schedule

Schedule a draft email campaign. Omitted From fields use the authenticated user at submission. Recipient membership is frozen at scheduling; acceptance is not delivery. Reuse the same requestId when retrying an uncertain operation.

## Execution

Interface: Creators MCP tool at https://mcp.creator.gg/mcp. Do not construct a REST route from the tool name. The connection selects the workspace.

Effect: changes workspace data. requestId is required by the service (8–128 characters); reuse it only for the same action and arguments.
This action has destructive or external-delivery effects. Resolve the user's requested scope before execution.

## Behavior and limits

Use a future timestamp with offset and matching IANA timeZone. Audience membership is frozen. Scheduling is not delivery.

## Example arguments

Illustrative placeholders only. Replace IDs with values from this workspace, resolve sender/content/recipients, recalculate dates, and generate a new requestId for a new action.

```json
{
  "campaignId": "campaign_example",
  "recipients": {
    "type": "tag",
    "tagIds": [
      "audience_example"
    ],
    "freezeList": true
  },
  "emailMeta": {
    "subject": "Product announcement",
    "fromName": "Example team",
    "fromEmail": "news@example.com"
  },
  "timeZone": "America/New_York",
  "sendAt": "2030-01-15T09:00:00-05:00",
  "requestId": "example-email_campaigns_schedule-001"
}
```

## Input schema

Generated from the current executable Creators contract. Runtime rules in Behavior and limits and the linked guide also apply; JSON Schema alone cannot express all cross-field constraints.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "recipients": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "contact"
            },
            "contactIds": {
              "minItems": 1,
              "maxItems": 100,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300,
                "pattern": "^[A-Za-z0-9_-]+$"
              }
            },
            "freezeList": {
              "default": true,
              "type": "boolean",
              "const": true
            }
          },
          "required": [
            "type",
            "contactIds"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "tag"
            },
            "tagIds": {
              "minItems": 1,
              "maxItems": 100,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300,
                "pattern": "^[A-Za-z0-9_-]+$"
              }
            },
            "freezeList": {
              "default": true,
              "type": "boolean",
              "const": true
            }
          },
          "required": [
            "type",
            "tagIds"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "segment"
            },
            "segment": {
              "type": "string",
              "enum": [
                "engaged_last_7_days",
                "engaged_last_30_days",
                "engaged_last_60_days",
                "engaged_last_5_campaigns",
                "unengaged_last_5_campaigns"
              ]
            },
            "freezeList": {
              "default": true,
              "type": "boolean",
              "const": true
            }
          },
          "required": [
            "type",
            "segment"
          ],
          "additionalProperties": false
        }
      ]
    },
    "emailMeta": {
      "type": "object",
      "properties": {
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "fromName": {
          "description": "Optional override. Defaults to the authenticated user's profile name, falling back to the workspace name.",
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "fromEmail": {
          "description": "Optional override. Defaults to the current email of the user who authorized this agent connection; workspace_status exposes defaultEmailSender. This does not verify sender/domain readiness.",
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        "replyToAddress": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        "previewText": {
          "type": "string",
          "maxLength": 500
        }
      },
      "required": [
        "subject"
      ],
      "additionalProperties": false
    },
    "timeZone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "sendAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "requestId": {
      "description": "Required by the Creators service for mutations: a stable 8–128 character identifier. Reuse on retries; change for a new action.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_.:-]{8,128}$"
    }
  },
  "required": [
    "campaignId",
    "recipients",
    "emailMeta",
    "sendAt"
  ],
  "additionalProperties": false
}
```

## Result interpretation

Results use status and message, with operation-specific data and optional link, code, nextAction, and operationId. Data may retain different list/record envelopes. A completed read or accepted send is not proof of delivery/publication. An unknown result must be reconciled. HUMAN_ACTION_REQUIRED returns instructions without performing the action.

## Related guides

- [email](https://docs.creator.gg/guides/email.md)
- [Recovery](https://docs.creator.gg/guides/recovery.md)
- [Unsubscribe and content](https://docs.creator.gg/guides/email-content.md)
- [Readiness](https://docs.creator.gg/guides/readiness.md)