',
subject: 'Exciting News from emailjs! 🎉',
});
console.log('Email sent successfully:', message);
} catch (err) {
console.error('Failed to send email:', err);
} finally {
client.smtp.close(); // Don't forget to close the connection!
}
}
sendMyEmail();
```
#### HTML Emails & Attachments
```javascript
import { SMTPClient, Message } from 'emailjs';
const client = new SMTPClient({
user: 'your-username',
password: 'your-password',
host: 'smtp.your-email.com',
tls: true,
});
async function sendRichEmail() {
const htmlContent = `
Greetings!
This is an HTML email with a lovely picture and an attachment.
Check out the attached file!
`;
const message = new Message({
from: 'You ',
to: 'Someone ',
subject: 'Your Awesome HTML Email! 🖼️📄',
attachment: [
{
data: htmlContent,
alternative: true, // This part is the HTML body
contentType: 'text/html',
},
{
path: 'path/to/your/document.pdf', // Attach a file from disk
type: 'application/pdf',
name: 'document.pdf',
},
{
path: 'path/to/your/image.jpg', // Embed an image for the HTML
type: 'image/jpeg',
name: 'cool_image.jpg',
// Reference in HTML with cid:my-image
headers: { 'Content-ID': '' },
},
],
});
try {
await client.sendAsync(message);
console.log('Rich email sent successfully!');
} catch (err) {
console.error('Failed to send rich email:', err);
} finally {
client.smtp.close();
}
}
sendRichEmail();
```
## API Reference 📖
The `emailjs` library is fully typed, here is a brief overview of most likely to
be used methods
### `new SMTPClient(options)`
Create a new client instance to connect to your SMTP server.
```javascript
const options = {
user: 'your-username', // 🔑 Username for logging into SMTP
password: 'your-password', // 🤫 Password for logging into SMTP
host: 'smtp.your-email.com', // 🌐 SMTP server host (defaults to 'localhost')
port: 587, // 🔌 SMTP port (defaults: 25 unencrypted, 465 SSL, 587 TLS)
ssl: true, // 🔒 Boolean or object for immediate SSL connection
tls: true, // 🔐 Boolean or object (see typescript types) to initiate STARTTLS
timeout: 5000, // ⏳ Max milliseconds to wait for SMTP responses
domain: 'your-domain.com', // 🏠 Domain to greet SMTP with (defaults to os.hostname)
authentication: ['PLAIN', 'LOGIN'], // 🤝 Preferred authentication methods
logger: console, // 📝 Override the built-in logger (e.g., custom logging)
};
```
### `SMTPClient#send(message, callback)`
Sends an email message. You can pass a `Message` instance or a headers object.
```javascript
client.send(messageObject, (err, details) => {
if (err) console.error(err);
else console.log('Message sent:', details);
});
```
### `SMTPClient#sendAsync(message)`
a promise-based way to send emails! ✨
```javascript
try {
const details = await client.sendAsync(messageObject);
console.log('Message sent:', details);
} catch (err) {
console.error('Failed to send:', err);
}
```
### `new Message(headers)`
Constructs an RFC2822-compliant message object.
```javascript
const headers = {
from: 'sender@example.com', // 💌 Sender (required!)
to: 'recipient@example.com', // 📬 Recipients (at least one of to, cc, or bcc)
cc: 'carbon-copy@example.com', // 👥 CC recipients
bcc: 'blind-copy@example.com', // 🕵️♀️ BCC recipients
subject: 'Your Subject Here', // 📝 Email subject
text: 'Plain text body.', // 🗒️ Plain text content
attachment: [{ data: 'Hello!' }], // 📎 One or more attachments
};
```
### `Message#attach(options)`
Adds an attachment to the message. Can be called multiple times.
```javascript
message.attach({
path: 'path/to/file.zip', // 📁 Path to a file on disk
data: 'Binary content as string or buffer', // 📄 Raw data
stream: fs.createReadStream('file.jpg'), // 🌊 A readable stream
type: 'application/zip', // MIME type
name: 'custom-name.zip', // Filename perceived by recipient
alternative: true, // attach inline as an alternative (e.g., HTML body)
inline: true, // If true, attached inline (e.g., for 
)
headers: { 'X-Custom-Header': 'value' }, // Custom attachment headers
});
```
### `Message#checkValidity()`
Synchronously validates that a `Message` is properly formed before sending.
```javascript
const { isValid, validationError } = message.checkValidity();
if (!isValid) {
console.error('Message is invalid:', validationError);
}
```
## Authors ✍️
* eleith
* zackschuster
## Testing 🧪
```bash
# Run all tests
npm test
# Run tests with code coverage report
npm run test:coverage
```
## Development 🧑💻🌱
for a local smtp testing experience, use our
[Mailpit](https://mailpit.axllent.org/) compose service
### 1. Start Mailpit with Docker Compose
Ensure you have Docker and Docker Compose installed.
```bash
# From the project root, start Mailpit
docker compose up
```
Mailpit will be accessible via:
* **Web UI:** `http://localhost:8025`
* **SMTP Server:** `localhost:1025`
### 2. Run Example Sending Scripts
You can use the provided scripts to send different types of emails to your local
Mailpit instance.
First, make sure the `emailjs` library is built:
```bash
npm run build
```
Then, run any of the example scripts:
```bash
# Send a plain text email
node scripts/send-text.js
# Send an HTML email
node scripts/send-html.js
# Send an email with attachments
node scripts/send-attachment.js
```
After running a script, open your Mailpit Web UI (`http://localhost:8025`) to
see the emails stream in! 📩
---
_Source: https://npm.io/package/emailjs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._