# @sapphirejs/mail

> Fluent Mail Client for Sapphire Framework

Latest version **0.0.15** (published 2018-04-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @sapphirejs/mail
pnpm add @sapphirejs/mail
yarn add @sapphirejs/mail
bun add @sapphirejs/mail
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.15 |
| Published | 2018-04-18 |
| First published | 2018-03-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 8.3.0 |
| Dependencies | 2 |
| Unpacked size | 16.2 KB |
| Known vulnerabilities | 0 (+15 in 2 direct dependencies) |
| Install scripts | no |
| Author | Fadion Dashi |
| Maintainers | aleksanderkoko, fadion |
| Keywords | mail, client, smtp, sapphire, framework |

## Links

- npm: https://www.npmjs.com/package/@sapphirejs/mail
- npm.io page: https://npm.io/package/@sapphirejs/mail

## Dependencies (2)

- [aws-sdk](https://npm.io/package/aws-sdk.md) ^2.205.0
- [nodemailer](https://npm.io/package/nodemailer.md) ^4.6.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 0.0.15 (latest) — 2018-04-18
- 0.0.14 — 2018-03-20
- 0.0.13 — 2018-03-19
- 0.0.12 — 2018-03-18
- 0.0.11 — 2018-03-11

## README

# Mail

A fluent email sender built as a thin wrapper on top of [nodemailer](https://github.com/nodemailer/nodemailer). It handles almost everything nodemailer does, but presents them in a more intuitive package. Actually supports STMP and SES transports, with plans to provide more in the future.

## Usage

```
$ npm install --save @sapphirejs/mail
```

We'll start with an exhaustive example that includes pretty much every option.

```javascript
const { Mail, Transport } = require('@sapphirejs/mail')

const config = { host: 'smtp.example.com' }
const mail = new Mail({}, new Transport.SMTP(config))
await mail.send('<p>Hi</p>', message => {
  message
    .from('from@domain.com')
    .replyTo('from@domain.com')
    .to('to@domain.com')
    .cc('cc@domain.com')
    .bcc('bcc@domain.com')
    .subject('Testing')
    .attach({ filename: 'file.txt', content: 'File' })
    .header('my-key', '123')
    .alternative('text/x-web-markdown', '**Email body**')
    .priority('low')
})
```

### HTML and Text Body

The first parameter of `Mail.send()` can be either a string as the HTML body, or an object that may set both the `text` and `html` versions. It is a good practice to include them both.

```javascript
await mail.send({ html: '<p>Hi</p>', text: 'Hi' }, /* rest of the message */)
```

### Global "from" Header

When the "from" header is passed as `Mail`'s config, it will be automatically included in every mail instance. Off course it also be overriden with the `from` function.

```javascript
const mail = new Mail({ from: 'from@domain.com' }, new Transport.SMTP(config))
```

### Name, Email Format

The `from`, `replyTo`, `to`, `cc`, and `bcc` headers can be set with a name followed by the email.

```javascript
message
  .from('John Smith', 'from@domain.com')
  .to('Jane Smith', 'to@domain.com')

// or as a single parameter

message
  .from('John Smith <from@domain.com>')
  .to('Jane Smith <to@domain.com>')
```

### Multiple Parameters

Multiple receivers, either `to`, `cc`, or `bcc`, can be chained to add more than one.

```javascript
message
  .to('John Smith<from@domain.com>')
  .to('Jane Smith<to@domain.com>')
```

The same applies to `header`, `attachment`, and `alternative`.

### Async

`Mail.send()` is an `async` function that returns a Promise and can be set to `await`. It will throw a `MailSendingFailed` if sending fails, or a `MissingMailParams` when the message headers aren't set correctly (ie: missing from field). Otherwise, it will return an info object with the details of the transport.

```javascript
try {
  const mail = new Mail({}, new Transport.SMTP(config))
  const result = await mail
    .send('<p>Hello</p>', message => {
      message
        .from('from@domain.com')
        .to('to@domain.com')
        .subject('Testing')
    })
} catch(err) {
  // handle the error
}
```

### SMTP Transport

The `SMTP` transport requires a configuration containing the server connection and authentication parameters. Most email services provide STMP options, so it should be a common transport for most use cases. A basic configuration is provided below, but you can read the [nodemailer docs](https://nodemailer.com/smtp/) for more advanced options like pooled connections, certificates, etc.

```javascript
const config = {
  host: 'smtp.thehost.com',
  port: 465,
  secure: false,
  auth: {
    user: 'user',
    pass: 'pass'
  }
}

const mail = new Mail({}, new Transport.SMTP(config))
```

### SES Transport

The `SES` transport connects to the SES API, a very reliable and affordable mail service. Please refer to the [AWS SDK docs](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html) for a list of configuration options, especially those in the section "Constructor Details".

```javascript
const config = {{
  accessKeyId: 'ACCESS_KEY',
  secretAccessKey: 'SECRET_KEY',
  region: 'us-east-1'
}

const mail = new Mail({}, new Transport.SES(config))
```

---
_Source: https://npm.io/package/@sapphirejs/mail · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._