Spec - Groups

Table Of Contents

• Create Group
• Get Groups
• Edit Groups
• Delete Groups
• Add Contacts to Group
• Delete Contacts from Group

Create Group

This function allows the caller to create a new group in the account.

Input

• Name of Group
• Type of Group (optional, should be Public, Private, or Hidden)
• EmailsSentFromName (optional)
• EmailsSentFromEmail (optional)
• EmailPhysicalAddress (optional)
• EventsTimeZone (optional)

For shared access user to create a group, include account_id (shared access user will need to have New Group Permissions).

Output

Success or error, ID of new group

Example Request

<CreateGroupRequest>
    <Name>MyNewGroup</Name>
    <GroupType>Hidden</GroupType>
    <EmailsSentFromName>Sally Simpson</EmailsSentFromName>
    <EmailsSentFromEmail>ssimpson@sample.com</EmailsSentFromEmail>
    <EmailPhysicalAddress>999 South Avenue, Coal City, KS, 70045, USA</EmailPhysicalAddress>
    <EventsTimeZone>America/Los_Angeles</EventsTimeZone>
</CreateGroupRequest>

Example Request (shared access)

<CreateGroupRequest account_id="123456">
    <Name>MyNewGroup</Name>
    <GroupType>Hidden</GroupType>
    <EmailsSentFromName>Joe Jackson</EmailsSentFromName>
    <EmailsSentFromEmail>jjackson@example.com</EmailsSentFromEmail>
    <EmailPhysicalAddress>333 First Avenue, Anytown, AL, 30221, USA</EmailPhysicalAddress>
    <EventsTimeZone>America/Los_Angeles</EventsTimeZone>
</CreateGroupRequest>

Successful Response

<CreateGroupResponse>
    <Result>Success</Result>
    <Group_id>9989</Group_id>
</CreateGroupResponse>

Get Groups

This function allows the caller to retrieve groups from the database. Search parameters should be specified inside the tag. Groups can be retrieved by ID or Name.

Input

Specify search criteria within GetGroupsRequest tag. Search criteria can be group_id or group_name. If no search criteria, return all groups in account. If not account owner, must pass account number. All groups that a shared user is a member of in that account would be passed.

Output

Success or failure. For each group found: Group_id, Name, Group_type, EmailsSentFromName, EmailsSentFromEmail, EmailPhysicalAddress, EventsTimeZone.

Example Request 1

<GetGroupsRequest></GetGroupsRequest>

Example Request 2

<GetGroupsRequest group_id="9985"></GetGroupsRequest>

Example Request 3

<GetGroupsRequest group_name="My Group"></GetGroupsRequest>

Example Request 4 (shared access)

<GetGroupsRequest account_id="123456" group_name="My Group"></GetGroupsRequest>

Successful Response

<GetGroupsResponse>
    <Result>Success</Result>
    <Groups>
        <Group>
            <AccountNumber>91234</AccountNumber>
            <Group_id>7</Group_id>
            <Name>TestQueueMail</Name>
            <Group_type>Private</Group_type>
            <EmailsSentFromName>Jeffery Samuels</EmailsSentFromName>
            <EmailsSentFromEmail>jsamuels@testco.com</EmailsSentFromEmail>
            <EmailPhysicalAddress>123 My Street, Mycity, CO, 90021, USA</EmailPhysicalAddress>
            <IncludeLoginLink>Yes</IncludeLoginLink>
            <EventsTimeZone>America/Los_Angeles</EventsTimeZone>
            <TotalMatchingContacts>28</TotalMatchingContacts>
        </Group>
        <Group>
            <AccountNumber>91234</AccountNumber>
            <Group_id>11</Group_id>
            <Name>MyTestGroupWithHiddenType</Name>
            <Group_type>Hidden</Group_type>
            <EmailsSentFromName>David Handler</EmailsSentFromName>
            <EmailsSentFromEmail>dhandler@anotherco.com</EmailsSentFromEmail>
            <EmailPhysicalAddress>456 Another Street, Altcity, MT, 89002, USA</EmailPhysicalAddress>
            <IncludeLoginLink>No</IncludeLoginLink>
            <EventsTimeZone>America/Los_Angeles</EventsTimeZone>
            <TotalMatchingContacts>54</TotalMatchingContacts>
        </Group>
    </Groups>
</GetGroupsResponse>

Edit Groups

This function allows the caller to edit one or more groups in the database. For a shared access user to edit a group, include account_id (shared access user will need to have New Group permissions).

Input

Specify search criteria within each Group tag. Search criteria can be:

• account_id (required for shared access users)
• group_id
• group_name
• request_id (optional)
• Name
• GroupType
• EmailsSentFromName
• EmailsSentFromEmail
• EmailPhysicalAddress
• EventsTimeZone

Each group’s search criteria must return a single unique group to edit. Any fields not sent will stay at their current values.

Output

For each Group ID, success or failure.

Example Request

<EditGroupsRequest>
    <Groups>
        <Group account_id="123456" group_id="5" request_id="a1b2c3">
            <Name>New Name</Name>
            <GroupType>Hidden</GroupType>
            <EmailsSentFromName>Joe Smith</EmailsSentFromName>
            <EmailsSentFromEmail>jsmith@mydomain.com</EmailsSentFromEmail>
            <EmailPhysicalAddress>123 First Street, Anytown, VA, 20345, USA</EmailPhysicalAddress>
            <EventsTimeZone>America/New_York/</EventsTimeZone>
        </Group>
        <Group account_id="123456" group_name="MyTestGroup222" request_id="d4e5f6">
            <Name>Another Name</Name>
            <EmailsSentFromName>Sam Smith</EmailsSentFromName>
            <EmailsSentFromEmail>ssmith@mydomain.com</EmailsSentFromEmail>
        </Group>
    </Groups>
</EditGroupsRequest>

Successful Response

<EditGroupsResponse>
    <Groups>
        <Group request_id="a1b2c3">
            <Group_id>5</Group_id>
            <Result>Success</Result>
        </Group>
        <Groups request_id="d4e5f6">
            <Group_id>6</Group_id>
            <Result>Success</Result>
        </Groups>
    </Groups>
</EditGroupsResponse>

Delete Groups

This function allows the caller to delete one or more groups from the database. For a shared access user to delete a group, include account_id (shared access user will need to have New Group permissions).

Input

Specify search criteria within each Group tag. Search criteria can be:

• account_id (required for shared access users)
• group_id
• group_name
• request_id (optional)

Each group’s search criteria must return a single unique group to delete.

Output

For each Group ID, success or failure.

Example Request 1

<DeleteGroupsRequest>
    <Groups>
        <Group group_id="5" request_id="a1b2c3" />
        <Group group_name="MyTestGroup222" request_id="d4e5f6" />
    </Groups>
</DeleteGroupsRequest>

Example Request 2 (Shared Access)

<DeleteGroupsRequest>
    <Groups>
        <Group account_id="123456" group_id="5" />
        <Group account_id="123456" group_name="MyTestGroup222" />
    </Groups>
</DeleteGroupsRequest>

Successful Response

<DeleteGroupsResponse>
    <Groups>
        <Group request_id="a1b2c3">
            <Group_id>5</Group_id>
            <Result>Success</Result>
        </Group>
        <Group request_id="d4e5f6">
            <Group_id>6</Group_id>
            <Result>Success</Result>
        </Group>
    </Groups>
</DeleteGroupsResponse>

Add Contacts to Group

This function allows the caller to add contacts to a group.

Input

• account_id (required for shared access users)
• group_id
• group_name
• request_id (optional)
• Contact
• contact_id
• firstname
• lastname
• email

Each contact’s search criteria must return a single unique contact to add to the group.

Output

For each Contact ID, success or failure.

Request Example 1

<AddContactsToGroupRequest group_id="9902">
    <Contacts>
        <Contact contact_id="8903" request_id="a1b2c3" />
        <Contact firstname="James" lastname="Johnson" request_id="d4e5f6" />
    </Contacts>
</AddContactsToGroupRequest>

Request Example 2 - shared access

<AddContactsToGroupRequest account_id="1234" group_name="My Group Name">
    <Contacts>
        <Contact contact_id="8903" />
        <Contact firstname="James" lastname="Johnson" />
    </Contacts>
</AddContactsToGroupRequest>

Successful Response

<AddContactsToGroupResponse>
    <Contacts>
        <Contact request_id="a1b2c3">
            <Contact_id>8903</Contact_id>
            <Result>Success</Result>
        </Contact>
        <Contact request_id="d4e5f6">
            <Contact_id>8904</Contact_id>
            <Result>Success</Result>
        </Contact>
    </Contacts>
</AddContactsToGroupResponse>

Delete Contacts from Group

This function allows the caller to delete contacts from a group.

Input

• account_id (required for shared access users)
• group_id
• group_name
• request_id (optional)
• Contact
• contact_id
• firstname
• lastname
• email

Each contact’s search criteria must return a single unique contact to delete from the group.

Output

For each Contact ID, success or failure.

Example Request 1:

<DeleteContactsFromGroupRequest group_id="9902">
    <Contacts>
        <Contact contact_id="8903" request_id="a1b2c3" />
        <Contact firstname="James" lastname="Johnson" request_id="d4e5f6" />
    </Contacts>
</DeleteContactsFromGroupRequest>

Request Example 2 - shared access:

<DeleteContactsFromGroupRequest account_id="1234" group_name="My Group Name">
    <Contacts>
        <Contact contact_id="8903" />
        <Contact firstname="James" lastname="Johnson" />
    </Contacts>
</DeleteContactsFromGroupRequest>

Successful Response

<DeleteContactsFromGroupResponse>
    <Contacts>
        <Contact request_id="a1b2c3">
            <Contact_id>8903</Contact_id>
            <Result>Success</Result>
        </Contact>
        <Contact request_id="d4e5f6">
            <Contact_id>8904</Contact_id>
            <Result>Success</Result>
        </Contact>
    </Contacts>
</DeleteContactsFromGroupResponse>