Sending Emails with EmailEngine

EmailEngine simplifies sending emails through registered accounts' SMTP servers or external sending services, making email management easier for applications without storing account credentials.

When you send an email using EmailEngine, it first queues the email for delivery. Then, it attempts to transfer the message to the account's SMTP server or the selected sending service.

By using EmailEngine, you avoid directly managing the credentials of individual email accounts. Instead, you only need access to EmailEngine and the account ID from which you wish to send the email.

See also: Sending emails using Email Templates and Mail-Merge.

API

Sending emails using the API

To send emails using the API, use the submit API endpoint.

Example Request:

curl -XPOST "http://127.0.0.1:3000/v1/account/example/submit" \
    -H "Authorization: Bearer f77cf263b704...9793022df08d91b9" \
    -H "Content-type: application/json" \
    -d '{
      "from": {
        "name": "Andris Reinman",
        "address": "andris@example.com"
      },
      "to": [
        {
          "name": "Ethereal",
          "address": "andris@ethereal.email"
        }
      ],
      "subject": "Test message",
      "text": "Hello from myself!",
      "html": "<p>Hello from myself!</p>"
    }'

Tip: The from address is optional. If not provided, EmailEngine uses the registered account email.

Response Example:

{
  "response": "Queued for delivery",
  "messageId": "<78aa92af-67c9-4130-b1bf-c22feb2ec3f6@example.com>",
  "sendAt": "2022-03-24T10:23:38.196Z",
  "queueId": "17fbb7408d44367d9b7"
}

Sending Raw Messages

For sending a pre-formatted RFC822 email, submit it as a base64-encoded raw property value. If the envelope property is not specified, recipients are derived from the email headers.

Example:

curl -XPOST "http://127.0.0.1:3000/v1/account/example/submit" \
    -H "Authorization: Bearer f77cf263b704...9793022df08d91b9" \
    -H "Content-type: application/json" \
    -d "{
      \"raw\" : \"` echo 'From: andris@example.com
To: andris@ethereal.email
Subject: test message
Mime-Version: 1.0

Hello world!
' | base64`\"
    }"

SMTP Interface

Sending via the bundled SMTP interface

To use EmailEngine’s bundled SMTP interface, enable it from the SMTP Interface configuration page.

Once enabled, configure your email sending library to use EmailEngine’s SMTP server. The SMTP username is the account ID, and the password is the SMTP password from the configuration page.

Note: EmailEngine’s SMTP server does not support TLS/SSL encryption, so make sure these settings are not configured.

Example SMTP Response:

250 Message queued for delivery as 17fbb0a97504803a15a (2022-03-24T08:28:27.856Z)

Client Library Examples:

Nodemailer:

const transporter = nodemailer.createTransport({
    host: 'localhost',
    port: 2525,
    auth: {
        user: 'example',
        pass: 'a57518a9e8858187463d53d5b7d3aa0c'
    }
});

PHPMailer:

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'localhost';
$mail->SMTPAuth = true;
$mail->Username = 'example';
$mail->Password = 'PUg6PzUe3ErkAKUqJ6';
$mail->Port = 2525;

SwiftMailer:

$transport = (new Swift_SmtpTransport('localhost', 2525))
  ->setUsername('example')
  ->setPassword('a57518a9e8858187463d53d5b7d3aa0c');

OAuth2 Integration

Gmail Accounts

Follow the steps for setting up OAuth2 with Gmail here.

Gmail Service Accounts

Instructions for setting up OAuth2 for service accounts can be found here.

Microsoft Accounts

Guide for OAuth2 setup for Microsoft accounts can be found here.

Open and Click Tracking

Tracking user action events

EmailEngine provides optional open and click tracking, which rewrites outgoing email HTML to route links through the tracking system. Tracked events generate webhook notifications for opens and clicks.

Enabling Tracking

  1. Navigate to the Service Configuration page.
  2. Enable "Sent Email Tracking."
  3. Configure webhooks for trackOpen and trackClick events.

API Options for Tracking

To enable tracking for a specific message, use the trackClicks and trackOpens options:

curl -XPOST "http://127.0.0.1:3000/v1/account/example/submit" \
    -H "Authorization: Bearer ..." \
    -H "Content-type: application/json" \
    -d '{
      "trackClicks": true,
      "trackOpens": true
    }'

Alternatively, use the X-EE-Tracking-Enabled SMTP header:

X-EE-Tracking-Enabled: true

Sample Webhook for trackOpen:

{
  "account": "example",
  "event": "trackOpen",
  "data": {
    "messageId": "<id@example.com>",
    "remoteAddress": "1.2.3.4",
    "userAgent": "Mozilla/5.0 ..."
  }
}

Delivery Delays

Send emails at a specific time

Schedule email delivery by specifying a sendAt time. Example:

curl -XPOST "http://127.0.0.1:3000/v1/account/example/submit" \
    -H "Authorization: Bearer ..." \
    -H "Content-type: application/json" \
    -d '{
      "sendAt": "2023-07-08T07:06:34.336Z"
    }'

SMTP Gateways

Send emails through an external service

Send emails through external services like SendGrid, Mailgun, or AWS SES by registering a gateway via API.

Register Gateway Example:

curl -XPOST "http://127.0.0.1:3000/v1/gateway" \
    -H "Authorization: Bearer ..." \
    -d '{
      "gateway": "sendgrid",
      "user": "apikey",
      "pass": "<YOUR_API_KEY>"
    }'

Then, send emails via the gateway by specifying it in the request:

curl -XPOST "http://127.0.0.1:3000/v1/account/example/submit" \
    -H "Authorization: Bearer ..." \
    -d '{
      "gateway": "sendgrid"
    }'

Outbox Management

Managing queued emails

EmailEngine allows you to list and delete emails that have been queued but are not yet transferred to the account's SMTP server. Outbox includes all emails that are scheduled to be delivered in the future, and it also contains emails that should have been sent but for whatever reason are not – for example, the SMTP server is currently not accessible.

Outbox is global as it includes queued emails for all accounts. It is not account-specific.

You can access the Outbox using the outbox API endpoints.

Bounces

You can read about detecting and handling bounces from here.

Replies and forwarding

EmailEngine includes helpers that mimic regular email clients when replying or forwarding emails. Read about it here.