# Email

Use Email to send text or HTML messages through Mailjet, with optional CC, BCC, and file attachments.

## Overview

**Type:** `email`

Mailjet credentials must be configured in the service deployment. Provide at least one of `textPart` or `htmlPart`. Sender, recipient, subject, and content fields accept [Morpher templates](/docs/morpher); attachment fields do not.

## Configuration

Put these fields in the step's `config` object. The examples below are configuration fragments; see [Execute workflows](/docs/execute-workflows) for the full request format. Supply their referenced variables in context.

### To

* **Type:** String
* **Required:** Yes
* **Templatable:** Yes
* **Pattern:** Valid email address format
* **Description:** Primary recipient email address

```
user@example.com
{{ user.email }}
{{ contact.email }}
```

### From

* **Type:** String
* **Required:** No
* **Default:** `noreply@reecall.co`
* **Templatable:** Yes
* **Pattern:** Valid email address format
* **Description:** Sender email address

```
noreply@company.com
{{ sender.email }}
support@{{ domain }}
```

### From name

* **Type:** String
* **Required:** No
* **Templatable:** Yes
* **Description:** Display name for the sender; defaults to the sender address

```
My Company
{{ brand.name }}
{{ department.name }} Team
```

### CC

* **Type:** Array of Strings
* **Required:** No
* **Templatable:** Yes
* **Description:** Carbon copy recipients

```json
["manager@example.com", "team@example.com"]
```

Or use templates:

```json
["{{ supervisor.email }}", "{{ department.email }}"]
```

### BCC

* **Type:** Array of Strings
* **Required:** No
* **Templatable:** Yes
* **Description:** Blind carbon copy recipients

```json
["archive@example.com"]
```

Or use a template:

```json
["{{ admin.email }}"]
```

### Subject

* **Type:** String
* **Required:** Yes
* **Templatable:** Yes
* **Max Length:** 255 characters
* **Description:** Email subject line

```
Welcome to our platform!
Order Confirmation - #{{ order.id }}
{{ notification.title }}
```

### Text part

* **Type:** String
* **Required:** No (but either textPart or htmlPart is required)
* **Templatable:** Yes
* **Multiline:** Yes
* **Description:** Plain text version of the email content

```
Hello {{ user.name }},

Thank you for joining us!

Best regards,
The Team
```

### HTML part

* **Type:** String
* **Required:** No (but either textPart or htmlPart is required)
* **Templatable:** Yes
* **Multiline:** Yes
* **Description:** HTML version of the email content

```html
<h1>Welcome {{ user.name }}!</h1>
<p>Thank you for joining us.</p>
<a href="{{ confirmationUrl }}">Confirm your account</a>
```

### Attachments

* **Type:** Array of Objects
* **Required:** No
* **Description:** Files to attach to the email. Attachment fields are sent as configured and are not processed as Morpher templates.

Each attachment object contains:

**filename**

* **Type:** String
* **Required:** Yes
* **Description:** Name of the attached file

**contentType**

* **Type:** String
* **Required:** Yes
* **Description:** MIME type of the file (e.g., `application/pdf`, `image/png`)

**base64Content**

* **Type:** String
* **Required:** Yes
* **Description:** Base64-encoded file content

```json
[
  {
    "filename": "invoice.pdf",
    "contentType": "application/pdf",
    "base64Content": "JVBERi0xLjQKJeLjz9MKMSAwIG9..."
  }
]
```

## Output

The Email step returns Mailjet's send response. A successful send response does not confirm delivery to the recipient's inbox.

```typescript
{
  messageId: number,    // Unique identifier assigned by Mailjet
  status: string,       // Delivery status (e.g., "success")
  to: string           // Recipient email address
}
```

### Accessing the output

```
{{ email_step.messageId }}
{{ email_step.status }}
```

## Examples

### Simple text email

```json
{
  "to": "{{ user.email }}",
  "from": "noreply@company.com",
  "fromName": "My Company",
  "subject": "Welcome!",
  "textPart": "Thank you for signing up, {{ user.name }}!"
}
```

### HTML email with personalization

```json
{
  "to": "{{ customer.email }}",
  "from": "orders@company.com",
  "fromName": "{{ company.name }}",
  "subject": "Order Confirmation - #{{ order.id }}",
  "htmlPart": "<h1>Thanks for your order!</h1><p>Hello {{ customer.name }},</p><p>Your order #{{ order.id }} has been confirmed.</p>",
  "textPart": "Thanks for your order!\n\nHello {{ customer.name }},\n\nYour order #{{ order.id }} has been confirmed."
}
```

### Email with CC recipients

```json
{
  "to": "{{ employee.email }}",
  "from": "hr@company.com",
  "fromName": "Human Resources",
  "cc": ["{{ manager.email }}", "hr-records@company.com"],
  "subject": "Performance Review Scheduled",
  "htmlPart": "<p>Your annual review is scheduled for {{ review.date }}.</p>"
}
```

### Email with BCC for tracking

```json
{
  "to": "{{ client.email }}",
  "from": "billing@company.com",
  "bcc": ["records@company.com"],
  "subject": "Invoice #{{ invoice.number }}",
  "htmlPart": "<h2>Invoice Details</h2><p>Amount due: ${{ invoice.amount }}</p>",
  "textPart": "Invoice Details\n\nAmount due: ${{ invoice.amount }}"
}
```

### Email with attachment

The Base64 value below is illustrative. Replace it with the complete encoded file before execution.

```json
{
  "to": "{{ user.email }}",
  "from": "reports@company.com",
  "fromName": "Reporting Team",
  "subject": "Your Monthly Report",
  "htmlPart": "<p>Please find your report attached.</p>",
  "textPart": "Please find your report attached.",
  "attachments": [
    {
      "filename": "report.pdf",
      "contentType": "application/pdf",
      "base64Content": "JVBERi0xLjQK"
    }
  ]
}
```

### Multi-recipient notification with both formats

```json
{
  "to": "team-lead@company.com",
  "from": "projects@company.com",
  "fromName": "Project Management",
  "cc": ["{{ member1.email }}", "{{ member2.email }}"],
  "bcc": ["notifications@company.com"],
  "subject": "Project Update - {{ project.name }}",
  "htmlPart": "<h2>{{ project.name }}</h2><p>Status: {{ project.status }}</p><ul><li>Progress: {{ project.progress }}%</li><li>Next milestone: {{ project.nextMilestone }}</li></ul>",
  "textPart": "{{ project.name }}\n\nStatus: {{ project.status }}\nProgress: {{ project.progress }}%\nNext milestone: {{ project.nextMilestone }}"
}
```

### Dynamic sender with conditional content

```json
{
  "to": "{{ user.email }}",
  "from": "{{ user.isPremium | lookup({'true': 'premium@company.com'}, 'support@company.com') }}",
  "fromName": "{{ user.isPremium | lookup({'true': 'Premium Support'}, 'Customer Support') }}",
  "subject": "{{ user.isPremium | lookup({'true': 'Premium'}, 'Standard') }} Account Update",
  "htmlPart": "<h1>Hello {{ user.name | capitalize }}!</h1><p>{{ user.isPremium | lookup({'true': 'Thank you for being a premium member.'}, 'Upgrade to premium for exclusive benefits.') }}</p>"
}
```

## Error handling

Missing content and Mailjet request failures throw `FLUX_EMAIL_ERROR`.

### Missing email content

When both `textPart` and `htmlPart` are absent or render as empty strings:

```typescript
{
  code: "FLUX_EMAIL_ERROR",
  message: "Email content is required. Provide either textPart or htmlPart"
}
```

### Invalid request (400)

```typescript
{
  code: "FLUX_EMAIL_ERROR",
  message: "Invalid email request: [error details]"
}
```

## Best practices

### Email addresses

* Validate email addresses before sending
* Use proper email format: `name@domain.com`
* Consider using email verification services for user-provided addresses

### Subject lines

* Keep subjects concise (50 characters or less recommended)
* Make subjects descriptive and relevant
* Personalize subjects when appropriate
* Avoid spam trigger words (FREE, WIN, URGENT in all caps)

### Email content

* Provide both `textPart` and `htmlPart` so clients that do not display HTML can use the plain text version.
* Use responsive HTML for better mobile experience
* Keep HTML simple and avoid complex CSS
* Test emails across different email clients
* Include unsubscribe links for marketing emails

### Attachments

* Keep total attachment size reasonable (Mailjet limits apply)
* Use appropriate MIME types for each file format
* Common content types:
  * PDF: `application/pdf`
  * PNG: `image/png`
  * JPEG: `image/jpeg`
  * Word: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
* Ensure Base64 encoding is correct
* Consider using links to large files instead of attachments
* Validate attachment content before encoding

### Compliance

* For US commercial email subject to CAN-SPAM, include a valid physical postal address and a clear opt-out mechanism. See the [FTC compliance guide](https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business).
* Provide clear unsubscribe mechanism
* Honor opt-out requests promptly
* Comply with CAN-SPAM, GDPR, and local regulations
* Keep records of consent for marketing communications
* Include privacy policy link when appropriate

## Common use cases

* **Welcome emails:** Greet new users upon registration
* **Order confirmations:** Confirm purchases with details and receipts
* **Password resets:** Send secure password reset links
* **Transactional notifications:** Notify users of account activity
* **Reports and analytics:** Deliver periodic reports with attachments
* **Invoices:** Send billing documents to customers
* **Team notifications:** Alert team members of important updates
* **Appointment reminders:** Reduce no-shows with email reminders
* **Marketing campaigns:** Send newsletters and promotional content
* **Account verification:** Send email confirmation links

## Troubleshooting

### HTML not rendering

* Validate HTML syntax
* Test with simple HTML first
* Ensure both `htmlPart` and `textPart` are provided
* Check email client compatibility
* Use inline CSS for better compatibility

### Attachments not working

* Verify Base64 encoding is correct
* Check `contentType` matches the actual file type
* Ensure total attachment size is within limits
* Test without attachments first to isolate issue
* Validate filename doesn't contain special characters

### Invalid request errors

* Verify all required fields are provided
* Check email address format (must match pattern)
* Ensure at least one of `textPart` or `htmlPart` is provided
* Validate template syntax in dynamic fields
