Virtual mailing lists

Allowing recipients to unsubscribe

When using Mail Merge to send emails, EmailEngine allows specifying an additional property, listId. If this value is set, then EmailEngine treats this message as a virtual mailing list email.

EmailEngine does not have "real" mailing list capabilities – there are no contact lists or segmentation rules, and there is no recorded history. Almost everything you'd expect from a mailing list manager is missing from EmailEngine. Virtual mailing lists provide only a single feature – list-unsubscribe.

Sometimes, for example, for legal reasons, it might be necessary to offer an unsubscribe option to the recipients. Building all the required components only to support unsubscribing might be tedious, so EmailEngine provides it itself.

Using listId

All Mail Merge emails sent with the listId value are grouped into the same virtual list. If a recipient decides to unsubscribe from such a list, any following emails with the same listId to that recipient will be ignored and not sent.

Virtual lists are also global and not bound to any specific email account. For example, if you provide a SaaS service, you can assign all seats of a single organization to the same virtual list. If a recipient unsubscribes from an email sent by one account of an organization, other accounts of the same organization can't send mail to them anymore, either.

Sending list emails

The format for the listId value is a subdomain name. Those IDs do not require any registration, and you can come up with these ad hoc.

In addition to the listId value, there's an extra template variable rcpt.unsubscribeUrl that is replaced by an unsubscribe URL for the specific recipient.

curl -XPOST "https://example.com/v1/account/example/submit" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer test123" \
  -d '{
    "subject": "List email",
    "html": "<a href=\"{{ rcpt.unsubscribeUrl }}\">Unsubscribe</a>",
    "mailMerge": [
      {
        "to": {
          "name": "Andris Reinman",
          "address": "andris@ethereal.email"
        }
      }
    ],
    "listId": "my.special.list"
  }'

If andris@ethereal.email clicks on the unsubscribe link, the following email with the same listId for andris@ethereal.email is not sent out.

Manually blocking recipients

If you want to manually unsubscribe recipients from specific lists, you can use the Blocklist API.

curl -XPOST "https://example.com/v1/blocklist/my.special.list" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer test123" \
  -d '{
    "account": "example",
    "recipient": "andris@ethereal.email",
    "reason": "manual block"
  }'