> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldvisagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# E-mail

> Configure the WorldVisa email channel by connecting a provider like SendGrid, Postmark, Mailgun, Amazon SES, or Resend to deliver transactional emails.

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:

**Step 1**

### 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](#configuring-email-providers). Provider-specific steps are under [Supported providers](#supported-providers). To send a test before you connect a provider, use the demo email integration.

**Step 2**

### 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.

**Step 3**

### 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.

**Step 4**

### 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.

**Step 5**

### Trigger the workflow

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

1. Resolves the subscriber.
2. Selects the correct provider. See [Integration conditions](https://docs.worldvisagroup.com/developers/integrations/integration-conditions.md).
3. Renders the email template.
4. Delivers the message through the configured email integration.

> [!NOTE]
>
> Learn how to [build email template](https://docs.worldvisagroup.com/developers/workflow/add-notification-content/channels-template-editors.md#email-template-editor) 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.

> [!NOTE]
>
> For detailed setup guides for each integration, refer to the [Supported Providers](https://docs.worldvisagroup.com/developers/integrations/email#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` |

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

> [!NOTE]
>
> 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 \${WV_API_URL}/v1/events/trigger api endpoint for the EU region.

```bash theme={null}
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

```bash theme={null}
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"]
        }
    }
}'
```

> [!NOTE]
>
> **`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](https://docs.worldvisagroup.com/developers/integrations/integration-conditions.md). 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](https://docs.worldvisagroup.com/developers/integrations/integration-conditions.md) for the step. If the integration doesn't exist or isn't active, the step fails instead of falling back to the primary integration.

```bash theme={null}
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:**

1. **Step-level override** - **Highest priority**
2. **Workflow-level/channels-level override**
3. **Step configuration** (configured in workflow editor)
4. **Environment default layout** - **Lowest priority**

```bash theme={null}
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](https://docs.worldvisagroup.com/developers/integrations/email/resend.md).

```bash theme={null}
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.

> [card] [SendGrid](https://docs.worldvisagroup.com/developers/integrations/email/sendgrid.md)
>
> Learn how to use the SendGrid provider to send emails using WorldVisa.

> [card] [Resend](https://docs.worldvisagroup.com/developers/integrations/email/resend.md)
>
> Learn how to use the Resend provider to send emails using WorldVisa.

> [card] [Outlook 365](https://docs.worldvisagroup.com/developers/integrations/email/outlook365.md)
>
> Learn how to use the Outlook 365 provider to send emails using WorldVisa.

> [card] [Custom SMTP](https://docs.worldvisagroup.com/developers/integrations/email/custom-smtp.md)
>
> Learn how to use a Custom SMTP provider to send emails using WorldVisa.


## Related topics

- [SendGrid Email Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/email/sendgrid.md)
- [Custom SMTP Email Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/email/custom-smtp.md)
- [Introduction to WorldVisa CRM](https://docs.worldvisagroup.com/crm/introduction.md)
- [SendGrid](https://docs.worldvisagroup.com/developers/integrations/email/activity-tracking/manual-configuration/sendgrid.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.