# mail (/docs/cloud-code/module-reference/mail)



## What This Adds In Cloud Code [#what-this-adds-in-cloud-code]

* Transactional email sending from Cloud Code flows.
* Template-based sends and direct text/html sends.
* Reply helper with threading header handling.

## Quick Start [#quick-start]

```js
const Mail = require('mail');
Mail.send({
  to: 'customer@example.com',
  subject: 'Welcome',
  text: 'Welcome to our platform.'
});
```

## API [#api]

| Function                             | Params                      | Returns             | Notes                                                                                                |
| ------------------------------------ | --------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| `send(params)`                       | mail payload                | `boolean \| object` | Requires `to`; non-template mail also requires `subject` and `text`.                                 |
| `reply(params, rawHeaders, options)` | payload + raw header string | `boolean \| object` | Builds reply/thread metadata automatically. `options` supports `fallback_to` and `fallback_subject`. |

Common `send` payload fields:

* `to`, `subject`, `text`, `html`
* `template`, `variables`
* `attachments` (base64 entries)

## Practical Examples [#practical-examples]

```js
const Mail = require('mail');

Mail.send({
  to: request.params.email,
  template: 'order-confirmation',
  variables: {
    first_name: request.params.first_name,
    order_number: request.params.order_number
  }
});
```

```js
Mail.reply(
  {
    from: 'support@example.com',
    text: request.params.reply_text
  },
  request.params.raw_headers,
  {
    fallback_to: request.params.to,
    fallback_subject: 'Re: Support'
  }
);
```

## Failure Modes & Gotchas [#failure-modes--gotchas]

* Missing required fields can return falsey result instead of hard crash.
* Keep template variable keys stable with mail template definitions.
* Validate recipient email before send.

## Related Modules [#related-modules]

* [html](./html)
* [i18n](./i18n)