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

Sending requests might occasionally time out or get killed, which does not necessarily mean the email was not sent. If a request times out, there's no reliable way to check if the email was queued or processed, so retrying might result in duplicate deliveries.

To avoid this, EmailEngine supports an Idempotency-Key. The Idempotency-Key is a unique identifier you provide to mark a specific email sending request. If an email has already been sent with the same key, EmailEngine will not resend it but will return the same response as before. You can safely retry sending without creating duplicates.

To use this feature, include the Idempotency-Key value.

Using the API

Add the Idempotency-Key header to the API request:

curl -X 'POST' \
  'https://ee.example/v1/account/example/submit' \
  -H 'Idempotency-Key: UNIQUE_VALUE' \
  -H 'Content-Type: application/json' \
  -d '{...}'

Using the SMTP gateway

Add the X-EE-Idempotency-Key message header:

From: andris@headless.email
To: Andris Ethereal <andris@ethereal.email>
X-EE-Idempotency-Key: UNIQUE_VALUE

Use the same Idempotency-Key value whenever retrying the same email.

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.