Virtual Mailing Lists

Allow recipients to unsubscribe

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

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

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

Using listId

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

Virtual lists are 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.

Unsubscribe Flow

Screenshot_2022-11-11_at_11.53.12.png

Unsubscribe Link in the Email

Each recipient of the Mail Merge operation will get a unique unsubscribe link. Compatible email clients will also display a one-click unsubscribe link or button.

Screenshot_2022-11-11_at_11.58.34.png

Unsubscribe Form

If the recipient clicks on the unsubscribe link, they are directed to an unsubscribe form hosted by EmailEngine, where they can confirm their request. If needed, they can re-subscribe if they change their mind.

Sending List Emails

The format for the listId value is a subdomain name. These IDs do not require any registration, and you can come up with them 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.

Example:

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

Note: If andris@ethereal.email clicks on the unsubscribe link, any subsequent emails with the same listId sent to andris@ethereal.email will not be sent.

Manually Blocking Recipients

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

Example:

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