Sending Emails with EmailEngine

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`\"
    }"

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');

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.

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 ..."
  }
}

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"
    }'

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"
    }'

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.

You can read about detecting and handling bounces from here.

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