CampaignEmails

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/growsurf-com/json-schema/growsurf-com-campaign-emails-schema.json",
  "title": "CampaignEmails",
  "description": "A program's email configuration (the dashboard Program Editor's Emails tab). Each property is an editable email template; the set of templates available depends on the program type (referral vs affiliate), and writing a template that is not available for the program type returns a `400`. The `settings` object holds sender, contact, and design settings. To see the full object with every template and its current values, `GET` this resource, then `PATCH` back only the fields you want to change.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/growsurf-com-openapi.json#/components/schemas/CampaignEmails",
  "type": "object",
  "properties": {
    "welcomeNonReferred": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Welcome email sent to a participant who joins on their own, without being referred. Available for both referral and affiliate programs."
    },
    "welcomeReferred": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Welcome email sent to someone who signs up through another participant's referral link (also covers referrals you add from the dashboard). Referral programs only."
    },
    "offerClaimed": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to a referred visitor who saves an offer through the Claim Offer Popup. It sends only while the popup is enabled and replaces the welcome-referred email for that visitor, so they receive one email. Available for both referral and affiliate programs."
    },
    "referralLinkViewedFirstTime": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to a participant the first time their referral link is viewed. It goes out only once. Available for both referral and affiliate programs."
    },
    "referralLinkUsed": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to a referrer when they earn referral credit because someone they referred completed the qualifying action. Most useful when a reward needs more than one referral to unlock. Labeled \"Referral Credit Received\" in the Program Editor. Referral programs only."
    },
    "referredSignup": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to a referrer each time someone signs up using their referral link. Labeled \"Referral Link Used\" in the Program Editor. Available for both referral and affiliate programs."
    },
    "goalAchieved": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to a participant when they unlock a reward (and to the referred friend as well, for double-sided rewards). Labeled \"Reward Unlocked\" in the Program Editor. Referral programs only."
    },
    "campaignEndedWinners": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to every participant who unlocked at least one reward, once the program ends. Referral programs only."
    },
    "campaignEndedNonWinners": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to every participant who did not unlock a reward, once the program ends. Referral programs only."
    },
    "followUpReminder": {
      "$ref": "#/$defs/CampaignFollowUpReminderEmailTemplate",
      "description": "Optional email to the referrer about directly invited contacts who have not completed signup after the configured delay (2–30 days, default 3). Disabled by default. Only new invitations created while this email is enabled qualify automatically. A later offer claim preserves invitation eligibility until signup; popup-only claims never qualify. Each contact is included once, grouped into one email per referrer. Available for referral and affiliate programs. The email does not send invitations to those contacts."
    },
    "progressUpdateMonthly": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "A month-end summary emailed to participants recapping how they are doing in the program. Available for both referral and affiliate programs."
    },
    "commissionGenerated": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to an affiliate when they earn a new commission, for example when a customer they referred makes a purchase. Affiliate programs only."
    },
    "commissionAdjusted": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to an affiliate when one of their commissions is adjusted because of a full refund, partial refund, or chargeback. Affiliate programs only."
    },
    "payoutPending": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to an affiliate when a batch payment is started and they have a payout on the way. Affiliate programs only."
    },
    "payoutSentSuccess": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sent to an affiliate when their payout completes successfully. Labeled \"Payout Sent Successfully\" in the Program Editor. Affiliate programs only."
    },
    "invite": {
      "$ref": "#/$defs/CampaignInviteEmailTemplate",
      "description": "The invitation email a participant sends to friends. Applies only when the program sends invites on the company's behalf (Design > Share > Invite, with your company as the sender). Its `useCompanyReplyTo` field sets whether replies go to your company or to the participant who sent the invite. Available for both referral and affiliate programs."
    },
    "loginLink": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "The one-time sign-in link emailed to returning participants. Applies when participant sign-in is required (in Options). Labeled \"One-Time Login Link\" in the Program Editor. This is a transactional email, so its on/off toggle cannot be changed. Available for both referral and affiliate programs."
    },
    "payoutDestinationConfirmation": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Asks a participant to confirm the payout destination where they will receive payouts (for example a PayPal or Wise email address). The body may use `{{payoutProvider}}` for the provider name and must keep the `{{payoutDestinationConfirmationLink}}` confirmation link. This is a transactional email, so its on/off toggle cannot be changed. Available for both referral and affiliate programs."
    },
    "payoutDestinationChanged": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Tells a participant that their payout destination changed. The body must keep `{{payoutDestinationMaskedEmail}}` so the notice identifies the new destination without showing the full address. This is a transactional email, so its on/off toggle cannot be changed. Available for both referral and affiliate programs."
    },
    "taxInfoMissing": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Asks a participant to submit the tax information required before they can be paid. Sends only when the program collects tax information. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."
    },
    "taxInfoReceived": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Confirms to a participant that the tax information they submitted was received. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."
    },
    "taxInfoApproved": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Tells a participant that their tax form is complete and approved. Labeled \"Tax Form Complete\" in the Program Editor. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."
    },
    "taxInfoRejected": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Tells a participant that their tax information was rejected and needs to be resubmitted. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."
    },
    "affiliateApplicationReceived": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Confirms to an applicant that their affiliate application was received and is under review. Sends when the program reviews public signups (an `affiliateApplicationMode` of `MANUAL_REVIEW` or `AUTO_APPROVE`). This is a transactional email, so its on/off toggle cannot be changed. Affiliate programs only."
    },
    "affiliateApplicationApproved": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Tells an applicant that their affiliate application was approved and welcomes them into the program. This is a transactional email, so its on/off toggle cannot be changed. Affiliate programs only."
    },
    "affiliateApplicationDenied": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Tells an applicant that their affiliate application was not approved. This is a transactional email, so its on/off toggle cannot be changed. Affiliate programs only."
    },
    "inviteAffiliate": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Invites a prospective affiliate to join the program. The body must keep `{{affiliateInviteLink}}`. This is a promotional email, so its on/off toggle can be changed. Affiliate programs only."
    },
    "affiliateApplicationStatusLink": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Sends an applicant a secure link to view their affiliate application status. Applies when `affiliateApplicationMode` is `MANUAL_REVIEW` or `AUTO_APPROVE`. The body must keep `{{applicationStatusLink}}`. This is a transactional email, so its on/off toggle cannot be changed. Affiliate programs only."
    },
    "affiliateApplicationEmailCorrection": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Asks an applicant to confirm a corrected email address before their affiliate application is updated. The body must contain `{{identityVerificationLink}}`. This is a transactional email, so its on/off toggle cannot be changed. Affiliate programs only."
    },
    "affiliateEmailChangeVerification": {
      "$ref": "#/$defs/CampaignEmailTemplate",
      "description": "Asks an affiliate to confirm a new account email address before it is updated. The body must contain `{{identityVerificationLink}}`. This is a transactional email, so its on/off toggle cannot be changed. Affiliate programs only."
    },
    "settings": {
      "$ref": "#/$defs/CampaignEmailSettings",
      "description": "Sender, contact, and design settings for the program's emails (the Emails > Settings sub-page)."
    }
  },
  "$defs": {
    "CampaignEmailContactSettings": {
      "type": "object",
      "description": "The physical mailing address shown in your email footers (required by anti-spam laws such as the US CAN-SPAM Act).",
      "properties": {
        "companyName": {
          "type": "string",
          "maxLength": 255,
          "description": "Required."
        },
        "addressLine1": {
          "type": "string",
          "maxLength": 255,
          "description": "Required."
        },
        "addressLine2": {
          "description": "Second address line shown in email footers.",
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255
        },
        "city": {
          "type": "string",
          "maxLength": 255,
          "description": "Required."
        },
        "state": {
          "description": "State, province, or region shown in email footers.",
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255
        },
        "postalCode": {
          "description": "Postal or ZIP code shown in email footers.",
          "type": [
            "string",
            "null"
          ],
          "maxLength": 100
        },
        "country": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 100,
          "description": "Free-text country (not validated as an ISO code)."
        }
      }
    },
    "CampaignEmailDesignSettings": {
      "type": "object",
      "properties": {
        "layoutMode": {
          "type": "string",
          "enum": [
            "INLINE"
          ],
          "readOnly": true,
          "description": "New programs use `INLINE`: place `{{emailFooter}}` in each email body to include the complete shared footer. `{{emailHeader}}` is optional; without it, the shared header appears above the body. This field is read-only. Older programs omit it and keep their existing layout."
        },
        "header": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 150000,
          "description": "Email header HTML."
        },
        "footer": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 150000,
          "description": "Email footer HTML."
        },
        "unsubscribePromotional": {
          "type": "string",
          "maxLength": 150000,
          "description": "Unsubscribe footer for promotional emails. Must contain the tokens `{{unsubscribeLink}}`, `{{companyName}}`, and `{{address}}`."
        },
        "unsubscribeInvite": {
          "type": "string",
          "maxLength": 150000,
          "description": "Unsubscribe footer for invite emails. Must contain the tokens `{{unsubscribeLink}}`, `{{companyName}}`, and `{{address}}`."
        },
        "unsubscribeAffiliateInvite": {
          "type": "string",
          "maxLength": 150000,
          "description": "Unsubscribe footer for direct affiliate invitation emails. Must contain the tokens `{{unsubscribeLink}}`, `{{companyName}}`, and `{{address}}`."
        },
        "unsubscribeTransactional": {
          "type": "string",
          "maxLength": 150000,
          "description": "Footer for transactional emails. Must contain the tokens `{{companyName}}` and `{{address}}`."
        }
      }
    },
    "CampaignEmailSenderSettings": {
      "type": "object",
      "properties": {
        "fromName": {
          "type": "string",
          "maxLength": 100,
          "description": "The email sender name. Required; cannot be an email address."
        },
        "replyToEmail": {
          "type": "string",
          "maxLength": 100,
          "description": "The reply-to email address. Required; must be a valid email address."
        },
        "fromEmail": {
          "type": "string",
          "readOnly": true,
          "description": "The from email address. Read-only — setting a custom from-address requires domain verification in the dashboard."
        }
      }
    },
    "CampaignEmailSettings": {
      "type": "object",
      "description": "Email sender, contact, and design settings (the Emails → Settings sub-page).",
      "properties": {
        "sender": {
          "description": "Sender name and reply-to settings for program emails.",
          "$ref": "#/$defs/CampaignEmailSenderSettings"
        },
        "contact": {
          "description": "Physical mailing address shown in program email footers.",
          "$ref": "#/$defs/CampaignEmailContactSettings"
        },
        "design": {
          "description": "Design settings shared across program emails.",
          "$ref": "#/$defs/CampaignEmailDesignSettings"
        }
      }
    },
    "CampaignEmailTemplate": {
      "type": "object",
      "description": "A single editable email template. `subject` and `preheader` are capped at 255 characters; `body` is HTML capped at 150000 characters.",
      "properties": {
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "The email's subject line. Required, so it cannot be empty. Supports dynamic text (`{{...}}` tokens), the same as the body."
        },
        "preheader": {
          "type": "string",
          "maxLength": 255,
          "description": "The preview text shown after the subject line in most inboxes."
        },
        "body": {
          "type": "string",
          "maxLength": 150000,
          "description": "The email body as HTML. When `settings.design.layoutMode` is `INLINE`, the body must include `{{emailFooter}}`; `{{emailHeader}}` is optional. You can personalize it with dynamic text, inserting `{{...}}` tokens like `{{firstName}}` or `{{shareUrl}}` to tailor each email to its recipient. See [Guide to using dynamic text in GrowSurf emails](https://support.growsurf.com/article/213-guide-to-using-dynamic-text-in-growsurf-emails)."
        },
        "isEnabled": {
          "type": "boolean",
          "description": "Whether this email is enabled. Read-only for transactional emails and the participant-to-friend `invite` email; promotional emails can be toggled."
        }
      }
    },
    "CampaignFollowUpReminderEmailTemplate": {
      "description": "Optional reminder to the referrer. The delay applies to newly scheduled contacts; existing reminder dates stay unchanged.",
      "allOf": [
        {
          "$ref": "#/$defs/CampaignEmailTemplate"
        },
        {
          "type": "object",
          "properties": {
            "delayDays": {
              "type": "integer",
              "minimum": 2,
              "maximum": 30,
              "default": 3,
              "description": "Days to wait before reminding the referrer. Available in email text as `{{followUpDelayDays}}`."
            }
          }
        }
      ]
    },
    "CampaignInviteEmailTemplate": {
      "description": "The participant-to-friend `invite` email. It is the only template with a reply-to choice; every other template uses your program's reply-to address.",
      "allOf": [
        {
          "$ref": "#/$defs/CampaignEmailTemplate"
        },
        {
          "type": "object",
          "properties": {
            "useCompanyReplyTo": {
              "type": "boolean",
              "description": "When `true`, replies go to your company's reply-to address, which keeps the referring participant's email address private (it is never exposed to the people they invite). When `false`, replies go to the referring participant."
            }
          }
        }
      ]
    }
  }
}