GreenArrow Email Software Documentation

Subscriber Records

Overview

Each subscriber in the system has a number of fields.

Fields

Email address

The email address of the subscriber.

An email address can only appear once on a mailing list.

The case of the email address is preserved by the system, but email addresses are always compared in a case-insensitive manner.

Leading and trailing whitespace is stripped whenever you enter an email address.

An email address is a valid local-part followed by an @ followed by a valid domain name.

A local-part may only contain the following characters:

  • Letters (a-z, A-Z)
  • Numbers (0-9)
  • Dashes (-)
  • Dots (.)
  • Underscores (_)
  • Plus signs (+)
  • Equal signs (=)
  • Percent signs (%)
  • Forward slashes (/)
  • Colons (:)
  • Semi-colons (;)
  • Question marks (?)
  • Exclamation marks (!)
  • Hash symbols (#)
  • Dollar signs ($)
  • Ampersands (&)
  • Single quotes (')
  • Asterisks (*)
  • Backticks (`)
  • Curly braces ({, })
  • Vertical pipes (|)
  • Tildes (~)

Additionally, a local-part must be between 1 and 256 characters long.

The domain part may be either:

  • An ASCII domain name. Valid characters are: letters (a-z and A-Z), numbers (0-9), dashes (-), underscore (_), and dots (.)
  • An Internationalized Domain Name (IDN), specifically the IETF IDNA2008 standard. This supports Unicode/UTF-8 characters. Not all Unicode characters are supported; for example upper case characters are not allowed; see RFC 5892 for more information on supported characters.

Additionally, the domain part:

  • May not contain two consecutive dots, or a dot at the beginning or the end.
  • May not contain a dash next to a dot or at the beginning or the end.
  • Must be between 1 and 256 characters long.
  • May not have the same form as an IP address. (For example: [email protected] or [email protected] are not valid email addresses and me@[162.168.0.1] is techincally a valid email address but it is not supported by GreenArrow Studio.)

Details of Internationalized Domain Name implementation

A strange quirk of Internationalized Domain Names is that a domain name containing non-ASCII characters is converted to a domain containing ASCII characters for use in non-unicode aware protocols. For example, test@ëxample.com converts to [email protected]. This is named punycoding. We call test@ëxample.com the unicode form and [email protected] the punycode form. Both forms are the same underlying email address, just different representations of it.

  • You can add a subscriber using either the unicode or the punycode form of the email address.
  • Whichever form you use to add the subscriber (or subsequently update it) will be returned when viewing the subscriber (through API, export, web-UI, etc).
  • Both the unicode and punycode form are considered the same email address, and for mailing lists without an alternate primary key only one can exist in the mailing list at the same time. For example, if you add a subscriber using the unicode form, then later try to add using the punycode form, you will get an error because the subscriber already exists in the mailing list.
  • When searching for a subscriber, you can search on either the unicode or the punycode form and regardless of what form was used to create the subscriber it will be found.
  • When the email address is sent to, the email is sent using the punycode form:
    • The recipient will see the punycode form in the To header (if their Mail User Agent does not decode punycoding).
    • The punycode form will be used for the email address replacement code and MD5 hash of the email address replacement code. (This may change in future versions.)
    • The punycode form will be shown in the Engine reports
    • The punycode domain will show in the “Domains with the Most Bounces”, “Spam Complaints”, and “SMTP” sections of the campaign and autoresponder statistics pages.
    • The punycode form will be provided to any Special Sending Rules. (This may change in future versions.)

There is one caveat: If you provide an email address that is partially punycode and partially unicode. For example, if you create a subscriber using user@點.xn--c1y.com then when viewing the subscriber the email address will be user@點.看.com and the email that will be sent to will be the fully punycoded version [email protected]. The system will consider all three of these addresses identical when querying subscribers. We strongly recommend against using partially punycode and partially unicode email addresses.

Status

This describes the status of a subscriber.

There is one active status:

Status Meaning
Active Subscriber is OK to be sent mail (i.e none of the above conditions apply.)

There are four inactive statuses:

Status Meaning
Unsubscribed Subscriber requested to stop getting mail, usually through clicking on an unsubscribe link.
Spam complaint Subscriber complained using a spam-complaint mechanism.
Bounced Due to receiving bounces, we determined this subscriber address is no longer valid.
Deactivated Don’t send to this subscriber because they are no longer part of the parent/source list. (See import feature.)

The inactive statuses have “precedence” in the above order, for example:

  • If the subscriber is set to bounced but then clicks on an unsubscribe link, their status will be set to unsubscribed, because unsubscribed is a higher precedence status than bounced.
  • If the subscriber is set to unsubscribed but we detect their email address is bad due to bounces, their status will not be changed, because it bounced is not a higher precedence than unsubscribed.

The subscribers on the list which have an inactive status is GreenArrow’s way of “remembering” these subscribers so that we don’t accidentally send mail to them again.

When importing to a mailing list, the default is to only update subscribers where the status is active. This keeps you from accidentally re-activating and sending to subscribers that bounced, unsubscribed, or generated a spam complaint.

Confirmed

This value only exists if the mailing list is set to have a confirmed field.

Valid values are: confirmed / unconfirmed.

The default for new subscribers is: confirmed.

Format

This value only exists if the mailing list is set to have a format field.

Valid values are: html / text.

The default for new subscribers is: html.

This can be used to store the preference of how the subscriber would like to receive their email. If you send an campaign that contains both a text and HTML portion to a list with the format field enabled, then

  • Subscribers with format=html will get multipart messages with HTML and text.
  • Subscribers with format=text will get text-only messages.

Subscribe Time

  • This is the time that the subscriber subscribed
  • This defaults to the time the subscriber is added. it may be overridden in the UI

Subscribe IP

  • The IP address the subscriber was using when they subscribed (if we have this information)

Confirm Time

  • This is the time that the subscriber was set to be confirmed
  • This will exist if the subscriber is confirmed, and will be blank if the subscriber is not confirmed

Confirm IP

  • The subscriber’s IP address when they confirmed by clicking on a confirmation link

Remove time

  • This is the time that the subscriber status was set to something other than active
  • This will exist if the subscriber status is not active, and will be blank if the subscriber status is active

Remove IP

  • This is the subscriber’s IP address when they caused the status to be set to something other than active, if we have it. (for example, their IP when clicking on an unsubscribe link.)

Finding Subscriber Records

If you have an email address you’d like to locate, GreenArrow provides the Manage Subscribers screen. In the “Mailing List” heading, navigate to the “Manage Subscribers” option.

On this screen, you can:

  • Enter an email address for which to search.
  • If you’re a system administrator, specify that you’d like to search across all organizations on the system.
  • Specify a single mailing list on which to search.

Enter your criteria and click “Submit” to search for subscriber records that match the given email address.

Require Confirmed Opt-In

An organization may be configured by the system administrator to require confirmed opt-in. When an organization requires confirmed opt-in, the following is true.

  1. Subscription Forms must have Confirmation Required turned on.
  2. Subscriber Imports are unavailable.
  3. Active subscribers created via the API must be created using a Subscription Form. See the Subscribers API for more information.
  4. Subscribers may still be added unconfirmed in the GreenArrow Studio web interface.
  5. Active subscribers can be added to the list in a way that bypasses confirmation. This is done by adding a non-active subscriber to the list, then updating its status to active. This process does not require confirmation. Additionally, the email address of a subscriber can be changed without required confirmation. (These paths that bypass confirmation may be closed in future releases of the software, so do not rely on them.)

To turn this on for an organization, navigate to that organization’s configuration page. Towards the bottom of the page is the Require Confirmed Opt‑In option.

Deleting Subscriber Records

Standard users must have the “Subscriber: Delete” permission enabled in order to delete subscriber records.

Subscribers can be deleted, but we don’t recommend this for general use. Typically, you should prefer to unsubscribe or deactivate subscribers instead of deleting them. This helps you to ensure that they don’t inadvertently rejoin your list after being removed.

However, if you need to delete subscribers for GDPR or other privacy law reasons, this is supported by GreenArrow.

In order to delete subscriber records, the configuration directive studio_disable_subscriber_deletion must not be enabled.


Copyright © 2012–2024 GreenArrow Email