1.1. M2_Contacts

1.1. M2_Contacts
Prev	1. Applications (Apps)	Next

This app has a client part that lets you add and remove contacts used for mass mailing purposes.

M2_Contacts::add($contact, [$groups], [$options])

$contact is a hash of details about the contact - the keys in the hash are listed here:

Table 1. Contact fields

Key	Description	Required
`email`	Email. This is validated thoroughly - we even check that the domain name exists in DNS.	Yes
`contact`	Name of the person. Sometimes you just have a company name and omit this.	No
`company`	Company name.	No
`mobile`	Mobile number. This must be prefixed with a plus sign and country code. We validate against an internal database of mobile number profiles, so if you have a valid number that doesn't validate it's most likely because we don't have a profile for that country - let us know.	No
`phone`	Land line phone number.	No
`address`	Address	No
`comments`	Internal comments about the contact.	No

Note

There is an intention to make this list of fields customizable per site.

$groups is an optional array of contact group IDs that you wish to place the contact in immediately. If you omit a group array, the contact will appear as an "orphan" in the administrative pages.

Note

The $groups array can also contain developer keys as set in the administrative pages. As these are "letters only" you can mix the array as you please between numeric group IDs and developer keys.

$options is an optional array of options to control the behavior of M2_Contacts::add():

Table 2. Contact options

Key	Description	Required
`overwrite`	If set to 1, you will overwrite an existing contact with an email matching this one. Otherwise an error is thrown if you try to overwrite.	No

M2_Contacts::getSubscriptionBlock([$options])

This method gives you a complete little widget containing a form for joining or leaving one or more contact groups.

The $options array holds the following keys:

Table 3. Contact options

Key	Description
`trans`	An associative array of translation keys and the strings to present in the HTML block. The keys are described in the table below.
`groups`	This can be either an array of group IDs/developer keys or a single value.

Table 4. Translation keys

Key	Description
`JOIN`	Label for the join button
`LEAVE`	Label for the lave button
`RULE_EMAIL_REQUIRED`	Message displayed if email is not filled in
`RULE_EMAIL_INVALID`	Message displayed if email seems invalid
`JOIN_CONFIRM`	Message displayed after joining
`LEAVE_CONFIRM`	Message displayed after leaving

M2_Contacts::remove($email)

$email is simply the email address of the contact you wish to remove. All group memberships are automatically discarded.

M2_Contacts::getGroups()

Returns an array of contact groups on your site. The ID of the groups are used as keys and each corresponding value is an array of info about the group:

Table 5. Contact group fields

Key	Description
`name`	Name of the group in the administration.
`developer_key`	The - optionally - assigned developer key which can be used to add and remove members to the group instead of the group ID.
`comment`	Any comment written about the group in the administration.