E-mail

Email providers are the services that deliver notifications to your subscribers’ email. You must set up each provider individually in the WorldVisa dashboard to enable delivery through the Email channel. WorldVisa provides a unified integration layer that connects your workflows to these email providers. Once you’ve added your integrations, WorldVisa handles routing and delivery automatically, sending each email through the correct provider without requiring additional setup. This allows you to manage multiple email integrations and switch providers when needed.

Key features

Multi-provider support: Integrate any major provider like SendGrid, SES, or Mailgun.
Activity tracking: Track delivery status, open rates, and more in the WorldVisa dashboard. See Activity Tracking.

How email works in WorldVisa

Here’s the typical flow for sending an email notification through WorldVisa:

Add an email provider

Connect an email provider in the Integration Store. You can connect more than one. Credentials, sender name, From address, and which integration is primary are in Configuring email providers. Provider-specific steps are under Supported providers. To send a test before you connect a provider, use the demo email integration.

Add the Email channel to your workflow

Next, include an Email step in a workflow. This step defines when and how an email should be sent as part of your notification workflow.

Define the email content

Within the Email step, you can design your message using the built-in visual editor or code editor. WorldVisa supports dynamic data from your payload, so each message can be personalized for the subscriber.

Store subscriber email addresses

WorldVisa automatically sends the notification to the email address stored on the subscriber’s profile. This profile is update either using the WorldVisa dashboard or API.

Trigger the workflow

Trigger the workflow from your application code by sending an event to WorldVisa. WorldVisa automatically:

Resolves the subscriber.
Selects the correct provider. See Integration conditions.
Renders the email template.
Delivers the message through the configured email integration.

Learn how to build email template using the block editor, custom HTML, and dynamic variables.

Configuring email providers

When you add an email provider in the Integration Store, you configure settings that are common to all email providers, as well as credentials specific to that provider.

Default sender settings

WorldVisa asks for two default settings for any email provider you connect:

Sender name: The name that appears in the recipient’s “From” field.
From email address: The email address the notification is sent from. For some email providers, including SendGrid, you must authenticate the From email address to make sure you’re sending an email from an authorized address.

These are the default values used for every email sent via this integration. You can override them when triggering a workflow if needed.

Provider authentication

You must provide credentials specific to your email provider for a successful integration.

For detailed setup guides for each integration, refer to the Supported Providers list at the bottom of this page.

Advanced email features

You can control advanced email features at runtime by passing data in your trigger call. This lets you send attachments, override default settings, or target a specific provider for a single notification.

Sending attachments

You can send attachments by passing an attachments array in the payload of your trigger. The attachment file can be provided as a buffer or a base64 encoded string. Each attachment object requires three fields:

Field	Type	Description
`file`	`Buffer` \| `string`	The file contents. Provide a `Buffer` or a pure base64 string — do not include a `data:<mime>;base64,` prefix.
`name`	`string`	The file name, including its extension (for example `report.pdf`).
`mime`	`string`	The MIME type of the file (for example `application/pdf`).

There is a total limit of 20MB for all attachments included in an email. Attachments are excluded from the 512KB trigger payload limit — see Payload Limits. Common MIME types you may need:

File type	MIME type
PDF (`.pdf`)	`application/pdf`
Word (`.docx`)	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Word (`.doc`)	`application/msword`
Excel (`.xlsx`)	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
CSV (`.csv`)	`text/csv`
Plain text (`.txt`)	`text/plain`
PNG (`.png`)	`image/png`
JPEG (`.jpg`, `.jpeg`)	`image/jpeg`
ZIP (`.zip`)	`application/zip`

Attachments belong in payload, not overrides. The overrides.email object is only for the fields listed in Sending email overrides (bcc, cc, from, replyTo, replaceToRecipient, senderName, text, to) — passing an attachments array there has no effect.

If your file value is a base64 data URL that starts with data:...;base64,, strip that prefix before triggering. WorldVisa expects the raw base64 payload only; passing the complete data URL produces invalid attachment content.

Use $/v1/events/trigger api endpoint for the EU region.

curl -L -X POST "${WV_API_URL}/v1/events/trigger" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <SECRET_KEY>' \
--data-raw '{
    "name": "workflow_trigger_identifier",
    "to": [
        {
            "subscriberId": "subscriber_id",
            "email": "email_address"
        }
    ],
    "payload": {
        "attachments": [
            {
                "file": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
                "name": "transparent.png",
                "mime": "image/png"
            },
            {
                "file": "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC",
                "name": "blue.png",
                "mime": "image/png"
            }
        ]
    }
}'

Sending email overrides

You can override the email settings for a single trigger by passing an overrides object. This lets you override the following fields:

bcc
cc
from address
replyTo
replaceToRecipient
senderName
text
to address

curl -L -X POST "${WV_API_URL}/v1/events/trigger" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId"
    },
    "overrides": {
        "email": {
            "to": ["to@example.com"],
            "from": "from@example.com",
            "senderName": "WorldVisa Team",
            "text": "text version of email using overrides",
            "replyTo": "no-reply@example.com",
            "cc": ["1@example.com"],
            "bcc": ["2@example.com"]
        }
    }
}'

replaceToRecipient

By default, WorldVisa merges override to addresses with the subscriber email.
Set replaceToRecipient: true to send only to override recipients. The subscriber email is omitted from to. to is replaced with the from address.
When replaceToRecipient is true, include at least one of to, cc, or bcc.

Empty to with cc/bcc (Custom SMTP only)

Setting to: [] with cc or bcc is supported only on Custom SMTP (Nodemailer).
WorldVisa normalizes an empty to to undisclosed-recipients:; so the message sends without exposing addresses in the To field.
Other email providers do not support this pattern.

Targeting a specific provider

By default, WorldVisa uses your primary email provider. To route automatically from subscriber or context data, see Integration conditions. To force a specific, active integration for a trigger, use the integrationIdentifier. This is useful if you have multiple active integrations for different purposes. For example, you might have one integration for transactional emails and one for marketing emails. You can find the integrationIdentifier for each provider in provider page in the Integration Store. When you pass integrationIdentifier in overrides.email, WorldVisa sends through that integration and doesn’t check integration conditions for the step. If the integration doesn’t exist or isn’t active, the step fails instead of falling back to the primary integration.

curl -L -X POST "${WV_API_URL}/v1/events/trigger" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId"
    },
    "overrides": {
        "email": {
            "integrationIdentifier": "brevo-abcdef"
        }
    }
}'

Overriding email layout

Each WorldVisa environment can have multiple layouts. Each email step in the workflow can have a layout assigned to it. Overriding the email layout allows you to dynamically override layout settings at trigger time, providing flexible layout management per workflow/channel or per step execution. layoutId values and its behavior:

Value	Behavior
”layout-identifier”	Uses layout with this identifier
”507f1f77bcf86cd799439011”	Uses layout with this MongoDB ObjectId
null	Explicitly no layout - renders email without any layout
undefined	Default behavior - uses step’s configured layout or environment default
Not specified	Same as undefined

Precedence rules:

Step-level override - Highest priority
Workflow-level/channels-level override
Step configuration (configured in workflow editor)
Environment default layout - Lowest priority

curl -L -X POST "${WV_API_URL}/v1/events/trigger" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId"
    },
    "payload": {},
    "overrides": {
        "channels": {
            "email": {
                "layoutId": "black-friday-layout"
            }
        },
        "steps": {
            "welcome-email": {
                "layoutId": "welcome-v2"
            },
            "promotional-email": {},
            "transactional-receipt": {
                "layoutId": null
            }
        }
    }
}'

Sending provider specific extra fields

You can send provider specific extra fields by passing a _passthrough object in the overrides object. This lets you send extra fields to the provider SDK. WorldVisa internally uses provider’s official SDK to send the email. Each provider has its own supported extra fields. Those extra fields are not validated by WorldVisa and are passed directly to the provider SDK. There are three type of fields that you can send: body, headers, and query. Below is an example of sending tags supported by Resend provider.

curl -L -X POST "${WV_API_URL}/v1/events/trigger" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId"
    },
    "payload": {},
    "overrides": {
        "providers": {
            "resend": {
                "_passthrough": {
                    "body": {
                        "tags": [
                            {
                                "name": "category",
                                "value": "confirm_email"
                            }
                        ]
                    },
                    "headers": {
                        "X-Custom-Header": "custom-header-value"
                    },
                    "query": {
                        "queryParam": "queryValue"
                    }
                }
            }
        }
    }
}'

Unsubscribe email

By default, WorldVisa does not add any unsubscribe links to the email. Few providers add unsubscribe links to the email by default. If you are looking to add custom unsubscribe links to the email, follow below steps:

Add {{payload.unsubscribeEmail}} field in the email editor.
Build custom unsubscribe link in your application using subscriberId workflowId. Make sure this link is secured with tokens to prevent abuse.
Use WorldVisa preference api to update the email channel preferences for this workflow to false.
Optionally, you can build a custom unsubscribe page and add the link of that page for unsubscribe email option.
Send the value of unsubscribeEmail variable in the payload while triggering the workflow.
WorldVisa will add the unsubscribe link to the email and end user will be able to unsubscribe from the email by clicking on the link.

Receiving email replies

Set replyTo to the mailbox where your team should receive replies. Sending a workflow email does not configure inbound reply processing; connect that mailbox to your application separately if you need to process responses.

Supported providers

Here are the email providers that are currently supported by WorldVisa. Select any provider to see its detailed setup guide.

SendGrid

Learn how to use the SendGrid provider to send emails using WorldVisa.

Resend

Learn how to use the Resend provider to send emails using WorldVisa.

Outlook 365

Learn how to use the Outlook 365 provider to send emails using WorldVisa.

Custom SMTP

Learn how to use a Custom SMTP provider to send emails using WorldVisa.

Getting Started

Integrate <Inbox />

Build a Workflow

Integrate Channels Providers

Account

Key features

How email works in WorldVisa

Add an email provider

Add the Email channel to your workflow

Define the email content

Store subscriber email addresses

Trigger the workflow

Configuring email providers

Default sender settings

Provider authentication

Advanced email features

Sending attachments

Sending email overrides

Targeting a specific provider

Overriding email layout

Sending provider specific extra fields

Unsubscribe email

Receiving email replies

Supported providers

SendGrid

Resend

Outlook 365

Custom SMTP

​Key features

​How email works in WorldVisa

​Add an email provider

​Add the Email channel to your workflow

​Define the email content

​Store subscriber email addresses

​Trigger the workflow

​Configuring email providers

​Default sender settings

​Provider authentication

​Advanced email features

​Sending attachments

​Sending email overrides

​Targeting a specific provider

​Overriding email layout

​Sending provider specific extra fields

​Unsubscribe email

​Receiving email replies

​Supported providers

SendGrid

Resend

Outlook 365

Custom SMTP

Key features

How email works in WorldVisa

Add an email provider

Add the Email channel to your workflow

Define the email content

Store subscriber email addresses

Trigger the workflow

Configuring email providers

Default sender settings

Provider authentication

Advanced email features

Sending attachments

Sending email overrides

Targeting a specific provider

Overriding email layout

Sending provider specific extra fields

Unsubscribe email

Receiving email replies

Supported providers