About the Automation Email Action API

The Automation Email Action API manages the "send email" actions of a site's automations: their settings, the email each action sends, the sender details assigned to it, and setting up new actions.

With the Automation Email Action API, you can:

• Set up a new send email action, ready to add to an automation.
• Retrieve and update a send email action's email type, notification topic, recipients and sender details.
• Retrieve and update a send email action's email content.
• Preview the rendered email content without sending it.
• Send a test email to check how the content looks in a real inbox.
• Retrieve and assign the sender details used to send the action's emails.

Send email actions are configured as part of a site's automation using the Automations V2 API. The action's configuration, its inputMapping, is internal to Wix. To add a new send email action, generate its input mapping with Generate Action Input Mapping and pass it to the Automations V2 API as is.

New send email actions

Generate Action Input Mapping sets up the action's email type, notification topic, recipient and sender, and creates the email content it sends. The content is the content you specify, or the default template's content if you don't specify any. On a multilingual site, the content is stored in the site's primary language, and the other languages start from the default template's content.

Every call creates new email content, so use each generated input mapping for a single action. Don't add it to more than one action: actions that share an input mapping share their email content, and removing one of them deletes the content the others send.

The email content stays a draft while the automation is a draft or inactive, and goes live when the automation is activated. After the action is added, manage its content with Set Email Content and its settings with Update Automation Email Action.

Action settings

Update Automation Email Action updates only the fields you send. Send a field as null to reset it to its default. Changes apply from the automation's next run, whether the automation is active or not.

A send email action is stored in its automation's configuration. Update Automation Email Action and Assign Sender Details increment the automation's revision, so retrieve the automation again before updating it with the Automations V2 API.

notificationTopicId isn't validated when the action is saved. Make sure the topic exists and matches emailType.

Recipients

recipients describes who the email is sent to. Its recipientType is one of:

• TRIGGER_CONTACT: The contact at triggerContactOptions.contactIdPath in the trigger payload, such as contactId.
• SITE_OWNER: The site owner. It has no options.
• CUSTOM: The participants of customOptions.audiences, as defined by the Audience API. Actions set up in the automations builder with other recipients, such as contacts with a label or several recipients at once, are CUSTOM.

Updating recipients replaces all the action's recipients. CUSTOM recipients whose single audience is the trigger contact or the site owner are returned as the equivalent TRIGGER_CONTACT or SITE_OWNER recipients.

Each audience's audienceProviderId is validated, but audienceProviderData and triggerContactOptions.contactIdPath aren't checked against what the provider or the trigger payload expects. Make sure they match, since a mismatch isn't reported when the action is saved.

Before you begin

It's important to note the following points before starting to code:

• An existing action isn't identified by an ID of its own. Address it by the automationId of the automation it belongs to and the actionId of the send email action within that automation. Find these values by retrieving the site's automations with the Automations V2 API and looking for an APP_DEFINED action whose actionKey is triggered-emails.
• A preinstalled automation starts out sharing its email content with every other site running the same automation. Get Email Content and Preview Email Content serve this shared content until a site edits it. Send Test Email requires content the site owns, so update it once first.
• Set Email Content replaces the stored content in full. The most reliable way to make a change is to first call Get Email Content and modify the result. WEB content in composer.composerDataJson is a proprietary structure, and an invalid value can prevent the content from being previewed or sent. To write content from scratch, use the MJML editor type.
• On a multilingual site, language selects a single translation of the content. Content structure is shared across languages, so only the text differs between them.
• Senders are managed with the Sender Details API. Pass the ID of a sender created there to Assign Sender Details. Get Assigned Sender Details returns an empty value when no sender is explicitly assigned, meaning the action uses the site's default sender details or a Wix-branded fallback.

Use cases

• Add a send email action to an automation
• Send an automation's email to contacts with a label
• Edit a preinstalled automation's email content for the first time
• Preview and test email content before it goes live
• Assign a sender to a send email action

Terminology

• Automation: A workflow, configured with the Automations V2 API, that runs a set of actions when a trigger occurs.
• Send email action: An automation action whose action key is triggered-emails, which sends an email when the automation runs.
• Input mapping: An action's configuration within an automation. A send email action's input mapping is internal to Wix, so it's generated rather than built.
• Preinstalled automation: An automation added to every site that installs the app that created it, rather than being specific to a single site.
• Sender details: A verified name and email address an email can be sent from, managed with the Sender Details API.