API Reference - ALPHA

The Groups.io API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by many API responses, when appropriate, including errors.

Note: The API is under active development. Items marked [NI] mean they are not yet implemented.

There is a group to discuss the API. If you have questions about the API or suggestions for improvements of the API or the docs, please post them there.

API Endpoint

api.groups.io

Versioning

When we make backwards-incompatible changes to the API, we release new, dated versions. The current version is XXX. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

To set the API version on a specific request, send a Groupsio-Version header.

What changes does Groups.io consider to be “backwards-compatible”?

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length of object IDs or other opaque strings.
  • You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups). Adding new event types.

Change Log

This section will list the changes made to the API over time, along with the associated Groupsio-Version header. While the API is being initially developed, this section will be blank.

Errors

Groups.io uses conventional HTTP response codes to indicate the success or failure of an API request. HTTP response code 200 indicates success and HTTP response code 400 indicates an error. In addition, when there is an error, an error object is returned, containing details of the error.

All API calls return an error object when there is an error, in addition to returning an HTTP 400 error code. Errors specific to API calls are listed with each API call. General errors, that can happen with any API call, are listed in this section.

Response Attributes
object
string, value is "error"

String representing the object’s type. Objects of the same type share the same value.
type

The type of error returned.
extra

Extra information, error specific.
General Errors
unauthorized

Incorrect email address or password.
bad_request

Incorrect parameters passed in. For example, a group id that doesn't exist.
authentication

Failure to properly authenticate yourself in the request.
expired

The supplied authentication token is too old.
rate_limit

Too many requests hit the API too quickly.
inadequate_permissions

You do not have permission to execute the specific API call.
invalid_value

When a value is unrecognized. The extra field will be set to the name of the field with the invalid value.
server

There was a problem with the server. Please try again later.
HTTP status code summary
200
OK

Everything worked as expected.
400
Bad Request

The request was unacceptable, often due to missing a required parameter.
429
Too Many Requests

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

Example Error Response

    {
      "object": "error",
      "type": "unauthorized",
      "extra": ""
    }

Libraries

The following are unofficial libraries.

JAVA

github.com/lake54/groupsio-api-java

Authentication

Authentication to the API is performed via HTTP Basic Auth, using a token received from the login API call. Provide the token as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail, as will requests made without HTTP Basic Auth.

Only the username field is used to provide information for authentication - for the login call, set it to your API key. The response will contain an API token which should be used as the username in all future requests until it expires.

Login

Authenticate a user and return a login object, including a token that is needed to access other API functions.

Query Parameters
email
required
string

The email address of the user.
password
required
string

The password of the user.
domain
optional
string

The domain to log in under. If not specified, groups.io is assumed.
twofactor
optional
number

If the user account is configured to require two factor authentication, the second factor from an Authenticator app.
Returns

Returns a login object if a valid email address/password pair is provided. Returns an error otherwise. If the account is configured to require two factor authentication, and the twofactor parameter is not provided, an two_factor_required is returned.

Successful Response Attributes
token
string

String representing the authentication token.
name
string

Name of the user, if there is one.

Definition

https://api.groups.io/v1/login

Example Request

$ curl "https://api.groups.io/v1/login?email=test@example.com&password=123456" \
-u API_KEY:

Example Successful Response

    {
        "token": "AUTHENTICATION_TOKEN",
        "name": "John Smith"
    }

Objects

Calls can return an object, or a list of objects, which can be paged through. Every object has an object parameter which identifies the object. Lists of objects also have an object parameter, set to list.

The Direct Add Results Object

Response Attributes
object
string, read-only, value is "direct_add_results"

String representing the object’s type. Objects of the same type share the same value.
total_emails
number

The total number of email addresses submitted for the direct add.
added_subs
array

An array of subscription objects representing the successful adds.
errors
array

An array of direct_add_error objects

object
string, read-only, value is "direct_add_error"

String representing the object’s type. Objects of the same type share the same value.
email
string

The email address that had an error.
status
string

The reason for the error, can be: direct_add_db_error, direct_add_invalid_email, direct_add_existing, direct_add_pending, direct_add_banned, direct_add_inactive.

Example Response

{
  "object": "direct_add_results",
  "total_emails": 2,
  "errors": [
    {
      "object": "direct_add_error",
      "email": "test@example.com",
      "status": "direct_add_invalid_email"
    }
  ],
  "added_members": [
    {
      "id": 701,
      "object": "subscription",
      "created": "2017-08-15T13:58:22.618029196-07:00",
      "updated": "2017-08-15T13:58:22.618029196-07:00",
      "user_id": 147,
      "group_id": 4,
      "status": "sub_status_normal",
      "post_status": "sub_poststatus_normal",
      "email_delivery": "email_delivery_single",
      "message_selection": "message_selection_all",
      "auto_follow_replies": false,
      "max_attachment_size": "max_attachment_size_small",
      "approved_posts": 0,
      "mod_status": "sub_modstatus_none",
      "pending_msg_notify": "sub_notify_email",
      "pending_sub_notify": "sub_notify_email",
      "sub_notify": "sub_notify_email",
      "storage_notify": "sub_notify_email",
      "sub_group_notify": "sub_notify_email",
      "message_report_notify": "sub_notify_email",
      "mod_permissions": "",
      "owner_msg_notify": "sub_ownermsg_notify_subs",
      "email": "john@smith.com",
      "user_status": "user_status_confirmed",
      "user_name": "",
      "timezone": "",
      "full_name": "John Smith",
      "about_me": "",
      "about_format": "about_html",
      "location": "",
      "website": "",
      "profile_photo_id": "",
      "profile_privacy": "profile_private",
      "dont_munge_message_id": false,
      "moderator_notes": "",
      "moderator_notes_updated": "0001-01-01T00:00:00Z",
      "use_signature": false,
      "use_signature_email": false
    }
  ]
}

The Group Object

Response Attributes
id
int, read-only
object
string, read-only, value is "user"

String representing the object’s type. Objects of the same type share the same value.
created
date, read-only

Created date
updated
date, read-only

Last updated date
title
string
name
string
alias
string
desc
string
subject_tag
string
footer
string
website
string
announce
boolean
moderated
boolean
new_users_moderated
boolean
unmoderate_users_after
number
restricted
boolean
allow_non_subs_to_post
boolean
force_html_emails
boolean
normalize_html_emails
boolean
reply_to
string

Can be: group_reply_to_group, group_reply_to_sender, group_reply_to_moderators, group_reply_to_group_and_sender
remove_other_reply_options
boolean
privacy
string

Can be: group_privacy_none, group_privacy_archives, group_privacy_unlisted, group_privacy_unlisted_public
members_visible
string

Can be: group_view_members_subs, group_view_members_moderators, group_view_members_owners
subgroup_access
string

Can be: sub_group_subs, sub_group_moderators, sub_group_owners
calendar_access
string

Access, can be: group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited
files_access
string

Access, can be: group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none
database_access
string

Access, can be: group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none
wiki_access
string

Access, can be: group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited
photos_access
string

Access, can be: group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none
member_directory_access
string

Access, can be: group_access_limited, group_access_moderators_only, group_access_none
polls_access
string

Access, can be: group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited
chat_access
string

Access, can be: group_access_limited, group_access_subscribers, group_access_none
handle_attachments
string

Can be: group_attachments_normal, group_attachments_bounced, group_attachments_stripped
plain_text_only
boolean
max_photo_size_email
string

Can be: max_photo_size_none, max_photo_size_small, max_photo_size_medium, max_photo_size_large, max_photo_size_ex_small, max_photo_size_medium_small, max_photo_size_somewhat_small
max_photo_size_photos
string

Can be: max_photo_size_none, max_photo_size_small, max_photo_size_medium, max_photo_size_large, max_photo_size_ex_small, max_photo_size_medium_small, max_photo_size_somewhat_small
max_photo_size_databases
string

Can be: max_photo_size_none, max_photo_size_small, max_photo_size_medium, max_photo_size_large, max_photo_size_ex_small, max_photo_size_medium_small, max_photo_size_somewhat_small
max_photo_size_wiki_images
string

Can be: max_photo_size_none, max_photo_size_small, max_photo_size_medium, max_photo_size_large, max_photo_size_ex_small, max_photo_size_medium_small, max_photo_size_somewhat_small
hash_tags_required
boolean
restrict_create_hash_tags
boolean
bounce_attachments
boolean
allow_photos_in_files
boolean
email_delivery_default
string

Email delivery, can be email_delivery_single, email_delivery_digest, email_delivery_special, email_delivery_none, email_delivery_html_digest, email_delivery_summary
message_selection_default
string

Message selection, can be message_selection_all, message_selection_follow_only, message_selection_follow_and_first_message
auto_follow_replies_default
boolean
max_attachment_size_default
string

Maximum attachment size, can be max_attachment_size_unlimited, max_attachment_size_small, max_attachment_size_medium, max_attachment_size_large, max_attachment_size_none
disable_edits
boolean
disable_no_email
boolean
auto_close_threads
boolean
close_threads_after
number
auto_moderate_threads
boolean
moderate_threads_after
number

Example Response

{
  "id": 5,
  "object": "group",
  "created": "2017-08-03T10:18:15.218974479-07:00",
  "updated": "2017-08-15T12:48:41.965409169-07:00",
  "title": "",
  "parent_group_id": 0,
  "name": "test",
  "alias": "main",
  "desc": "This is a description of a test group.",
  "subject_tag": "[test]",
  "footer": "This is my\r\nFooter!!!!",
  "website": "",
  "announce": false,
  "moderated": false,
  "new_users_moderated": true,
  "unmoderate_users_after": 1,
  "restricted": false,
  "allow_non_subs_to_post": false,
  "force_html_emails": false,
  "normalize_html_emails": false,
  "reply_to": "group_reply_to_group",
  "remove_other_reply_options": false,
  "privacy": "group_privacy_none",
  "members_visible": "group_view_members_subs",
  "subgroup_access": "sub_group_subs",
  "calendar_access": "group_access_limited",
  "files_access": "group_access_limited",
  "database_access": "group_access_limited",
  "wiki_access": "group_access_limited",
  "photos_access": "group_access_limited",
  "member_directory_access": "group_access_limited",
  "polls_access": "polls_access_subscribers",
  "chat_access": "group_access_limited",
  "handle_attachments": "group_attachments_normal",
  "plain_text_only": false,
  "max_photo_size_email": "max_photo_size_none",
  "max_photo_size_photos": "max_photo_size_none",
  "max_photo_size_databases": "max_photo_size_none",
  "max_photo_size_wiki_images": "max_photo_size_none",
  "hash_tags_required": false,
  "restrict_create_hash_tags": false,
  "bounce_attachments": false,
  "allow_photos_in_files": false,
  "email_delivery_default": "email_delivery_none",
  "message_selection_default": "message_selection_all",
  "auto_follow_replies_default": true,
  "max_attachment_size_default": "max_attachment_size_unlimited",
  "disable_edits": false,
  "disable_no_email": false,
  "auto_close_threads": false,
  "close_threads_after": 0,
  "auto_moderate_threads": false,
  "moderate_threads_after": 0
}

The Invite Results Object

Response Attributes
object
string, read-only, value is "invite_results"

String representing the object’s type. Objects of the same type share the same value.
total_emails
number

The total number of email addresses submitted for the invite.
invited
array

An array of email addresses that have been successfully invited.
errors
array

An array of invite_error objects

object
string, read-only, value is "invite_error"

String representing the object’s type. Objects of the same type share the same value.
email
string

The email address that had an error.
status
string

The reason for the error, can be: invite_db_error, invite_invalid_email, invite_existing, invite_pending, invite_banned, invite_inactive, invite_inactive, invite_normal, invite_not_confirmed, invite_bouncing, invite_reinvite.

Example Response

{
  "object": "invite_results",
  "total_emails": 2,
  "errors": [
    {
      "object": "invite_error",
      "email": "test@example.com",
      "status": "invite_invalid_email"
    }
  ],
  "invited": [ 
    "john@smith.com", 
    "bob@smith.com" 
  ]
}

The Permissions Object

Response Attributes
object
string, read-only, value is "permissions"

String representing the object’s type. Objects of the same type share the same value.
manage_subgroups
boolean, read-only
delete_group
boolean, read-only
view_archives
boolean, read-only
download_members
boolean, read-only
view_activity
boolean, read-only
manage_hashtags
boolean, read-only
manage_integrations
boolean, read-only
manage_group_settings
boolean, read-only
manage_group_billing
boolean, read-only
edit_archives
boolean, read-only
manage_pending_messages
boolean, read-only
invite_members
boolean, read-only
view_databases
boolean, read-only
can_post
boolean, read-only
manage_polls
boolean, read-only
view_photos
boolean, read-only
manage_photos
boolean, read-only
make_moderator
boolean, read-only
manage_member_subscription_options
boolean, read-only
manage_pending_members
boolean, read-only
remove_members
boolean, read-only
ban_members
boolean, read-only
manage_members
boolean, read-only
view_calendar
boolean, read-only
manage_calendar
boolean, read-only
view_chats
boolean, read-only
manage_chats
boolean, read-only
view_member_directory
boolean, read-only
view_files
boolean, read-only
manage_files
boolean, read-only
view_members
boolean, read-only
view_wiki
boolean, read-only
manage_wiki
boolean, read-only
manage_subscription
boolean, read-only

Example Response

{
  "object": "permissions",
  "manage_subgroups": true,
  "delete_group": true,
  "view_archives": true,
  "download_members": true,
  "view_activity": true,
  "manage_hashtags": true,
  "manage_integrations": true,
  "manage_group_settings": true,
  "make_moderator": true,
  "manage_member_subscription_options": true,
  "manage_pending_members": true,
  "remove_members": true,
  "ban_members": true,
  "manage_group_billing": true,
  "edit_archives": true,
  "manage_pending_messages": true,
  "invite_members": true,
  "view_databases": true,
  "can_post": true,
  "manage_polls": true,
  "view_photos": true,
  "manage_photos": true,
  "manage_members": true,
  "view_calendar": true,
  "manage_calendar": true,
  "view_chats": true,
  "manage_chats": true,
  "view_member_directory": true,
  "view_files": true,
  "manage_files": true,
  "view_members": true,
  "view_wiki": true,
  "manage_wiki": true,
  "manage_subscription": true
}

The Subscription Object

Attributes
id
number, read-only

Subscription ID
object
string, read-only, value is "subscription"

String representing the object’s type. Objects of the same type share the same value.
created
date, read-only

Created date
updated
date, read-only

Last updated date
user_id
number, read-only

User ID
group_id
number, read-only

Group ID
status
string

Subscription status, can be sub_status_normal, sub_status_pending, sub_status_banned
post_status
string

Posting status, can be sub_poststatus_normal, sub_poststatus_allowed, sub_poststatus_moderated, sub_poststatus_notallowed, sub_poststatus_newusermoderated
email_delivery
string

Email delivery, can be email_delivery_single, email_delivery_digest, email_delivery_special, email_delivery_none, email_delivery_html_digest, email_delivery_summary
message_selection
string

Message selection, can be message_selection_all, message_selection_follow_only, message_selection_follow_and_first_message
auto_follow_replies
boolean
max_attachment_size
string

Maximum attachment size, can be max_attachment_size_unlimited, max_attachment_size_small, max_attachment_size_medium, max_attachment_size_large, max_attachment_size_none
approved_posts
number, read-only
email
string, read-only
user_status
string, read-only

User status, can be user_status_not_confirmed, user_status_confirmed, user_status_inactive, user_status_bouncing, user_status_bounced
user_name
string, read-only
timezone
string, read-only
full_name
string
about_me
string
about_format
string
location
string
website
string
profile_privacy
string

Profile visibility, profile_private, profile_members, profile_public
dont_munge_message_id
boolean, read-only

Whether to change the message-id of any posted messages
moderator_notes
string

Free-form data. This will be empty if the object is 'subscription_plus'.
moderator_notes_updated
date, read-only
use_signature
boolean
use_signature_email
boolean
The following is moderator data
mod_status
string

Moderator status, can be sub_modstatus_none, sub_modstatus_moderator, sub_modstatus_owner
pending_msg_notify
string

Notify about pending messages, can be sub_notify_email, sub_notify_none
pending_sub_notify
string

Notify about pending subscriptions, can be sub_notify_email, sub_notify_none
sub_notify
string

Notify when someone joins the group, can be sub_notify_email, sub_notify_none
storage_notify
string

Notify when storage limits are reached, can be sub_notify_email, sub_notify_none
sub_group_notify
string

Notify when a subgroup is created, can be sub_notify_email, sub_notify_none
message_report_notify
string

Notify when someone reports a message, can be sub_notify_email, sub_notify_none
owner_msg_notify
string

Receive messages sent to the +owner address, can be sub_ownermsg_notify_all, sub_ownermsg_notify_subs, sub_ownermsg_notify_none
mod_permissions
string

Moderator permissions, comma separated list of zero or more ofthe following: sub_perm_pendingmsgs, sub_perm_pendingmembers, sub_perm_invitemembers, sub_perm_removemembers, sub_perm_banmembers, sub_perm_makemoderator, sub_perm_createhashtags, sub_perm_groupsettings, sub_perm_modsub, sub_perm_integrations, sub_perm_editarchives, sub_perm_billing, sub_perm_managesubgroups

Example Response

{
      "id": 701,
      "object": "subscription",
      "created": "2017-08-15T13:58:22.618029196-07:00",
      "updated": "2017-08-15T13:58:22.618029196-07:00",
      "user_id": 147,
      "group_id": 4,
      "status": "sub_status_normal",
      "post_status": "sub_poststatus_normal",
      "email_delivery": "email_delivery_single",
      "message_selection": "message_selection_all",
      "auto_follow_replies": false,
      "max_attachment_size": "max_attachment_size_small",
      "approved_posts": 0,
      "mod_status": "sub_modstatus_none",
      "pending_msg_notify": "sub_notify_email",
      "pending_sub_notify": "sub_notify_email",
      "sub_notify": "sub_notify_email",
      "storage_notify": "sub_notify_email",
      "sub_group_notify": "sub_notify_email",
      "message_report_notify": "sub_notify_email",
      "mod_permissions": "",
      "owner_msg_notify": "sub_ownermsg_notify_subs",
      "email": "john@smith.com",
      "user_status": "user_status_confirmed",
      "user_name": "",
      "timezone": "",
      "full_name": "John Smith",
      "about_me": "",
      "about_format": "about_html",
      "location": "",
      "website": "",
      "profile_photo_id": "",
      "profile_privacy": "profile_private",
      "dont_munge_message_id": false,
      "moderator_notes": "",
      "moderator_notes_updated": "1969-12-31T16:00:00-08:00",
      "use_signature": false,
      "use_signature_email": false
}

The Subscription Plus Object

The subscription plus object is a subscription object with some additional read-only fields, and with the member_notes field left blank. It is only returned by methods that fetch a user's own subscriptions. Note: these fields have meaningful values only in subscriptions for which the user is a moderator or owner.

Additional Attributes
num_subs
number, read-only

Number of subscriptions in the associated group.
pending_messages
number, read-only

Number of pending messages in the associated group.
pending_subs
number, read-only

Number of pending subscriptions in the associated group.
most_recent_message
date, read-only

Date of the most recent message.

Example Response

{
  "id": 50,
  "object": "subscription_plus",
  "created": "2017-08-07T21:32:07.757486408-07:00",
  "updated": "2017-08-15T13:11:56.114230103-07:00",
  "user_id": 3,
  "group_id": 7,
  "status": "sub_status_normal",
  "post_status": "sub_poststatus_normal",
  "email_delivery": "email_delivery_single",
  "message_selection": "message_selection_all",
  "auto_follow_replies": false,
  "max_attachment_size": "max_attachment_size_unlimited",
  "approved_posts": 0,
  "mod_status": "sub_modstatus_owner",
  "pending_msg_notify": "sub_notify_email",
  "pending_sub_notify": "sub_notify_email",
  "sub_notify": "sub_notify_email",
  "storage_notify": "sub_notify_email",
  "sub_group_notify": "sub_notify_email",
  "message_report_notify": "sub_notify_email",
  "mod_permissions": "",
  "owner_msg_notify": "sub_ownermsg_notify_subs",
  "email": "john@smith.com",
  "user_status": "user_status_confirmed",
  "user_name": "",
  "timezone": "America/Los_Angeles",
  "full_name": "John Smith",
  "about_me": "",
  "about_format": "about_html",
  "location": "",
  "website": "",
  "profile_photo_id": "",
  "profile_privacy": "profile_private",
  "dont_munge_message_id": false,
  "moderator_notes": "",
  "moderator_notes_updated": "0001-01-01T00:00:00Z",
  "use_signature": false,
  "use_signature_email": false,
  "num_subs": 1,
  "pending_messages": 0,
  "pending_subs": 0,
  "most_recent_message": "1969-12-31T16:00:00-08:00"
}

The User Object

A user represents all the information about the logged in user.

Attributes
id
number, read-only

ID of the user
object
string, read-only, value is "user"

String representing the object’s type. Objects of the same type share the same value.
created
date, read-only

Date the user was created
updated
date, read-only

Date the user was last updated
email
string

Email address of the user
full_name
string

Full name of the user
user_name
string

User name of the user
timezone
string

Timezone of the user
status
string

User status, user_status_not_confirmed, user_status_confirmed, user_status_inactive, user_status_bouncing, user_status_bounced
has_profile_photo
boolean

If the user has uploaded a photo
profile_photo_id
number

The ID of the profile photo
post_pref
string

Posting preference, user_postpref_html, user_postpref_plain, user_postpref_markdown
per_page_pref
string

Per page display preference, user_per_page_pref20, user_per_page_pref50, user_per_page_pref100, user_per_page_pref_infinite
allow_facebook_login
boolean

Whether login by Facebook is permitted
allow_google_login
boolean

Whether login by Google is permitted
two_factor_enabled
boolean, read-only

If 2Factor authentication is enabled
recovery_codes
string, read-only

If 2Factor authentication is enabled, these are the recovery codes
dont_munge_message_id
boolean

Whether to change the message-id of any posted messages
about_me
string

Profile about me information
about_format
string

Format of the about me, about_html, about_plain, about_markdown
location
string

Profile location information
website
string

Profile website
time_pref
string

How to display times, time_relative, time_absolute
profile_privacy
string

Profile visibility, profile_private, profile_members, profile_public
default_message_view
string

Which message view to display by default, thread_view, message_view, expanded_message_view, polls_view
topics_sort_dir
string

Default sort direction of topics, sort_none, sort_asc, sort_desc
topic_sort_dir
string

Default sort direction of an individual topic, sort_none, sort_asc, sort_desc
messages_sort_dir
string

Default sort direction of the messages view, sort_none, sort_asc, sort_desc
expanded_messages_sort_dir
string

Default sort direction of the expanded messages view, sort_none, sort_asc, sort_desc
search_sort
string

Default sort type for searches, relevance_sort, date_sort
search_sort_dir
string

Defualt sort direction of search, sort_none, sort_asc, sort_desc

Example Response

{
  "id": 3,
  "object": "user",
  "created": "2017-07-28T12:30:38.052553032-07:00",
  "updated": "2017-08-15T13:11:56.121635376-07:00",
  "email": "john@smith.com",
  "full_name": "John Smith",
  "user_name": "",
  "timezone": "America/Los_Angeles",
  "status": "user_status_confirmed",
  "profile_photo_id": "",
  "has_profile_photo": false,
  "post_pref": "user_postpref_markdown",
  "per_page_pref": "user_per_page_pref20",
  "allow_facebook_login": false,
  "allow_google_login": false,
  "two_factor_enabled": false,
  "recovery_codes": "",
  "dont_munge_message_id": false,
  "about_me": "",
  "about_format": "about_html",
  "location": "",
  "website": "",
  "time_pref": "time_relative",
  "profile_privacy": "profile_private",
  "default_message_view": "thread_view",
  "topics_sort_dir": "sort_desc",
  "topic_sort_dir": "sort_asc",
  "messages_sort_dir": "sort_none",
  "expanded_messages_sort_dir": "sort_none",
  "search_sort": "relevance_sort",
  "search_sort_dir": "sort_none"
}

User

Actions involving the authenticated user.

Get User

Return the user information associated with an authentication token.

Definition

https://api.groups.io/v1/getuser

Example Request

$ curl "https://api.groups.io/v1/getuser" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
  "id": 3,
  "created": "2017-08-03T10:18:15.218974479-07:00",
  "updated": "2017-08-03T10:21:22.482757663-07:00",
  "email": "john@smith",
  "full_name": "John Smith",
  "user_name": "",
  "timezone": "Pacific/Midway",
  "status": "user_status_confirmed",
  "profile_photo_id": "",
  "has_profile_photo": false,
  "post_pref": "user_postpref_markdown",
  "per_page_pref": "user_per_page_pref20",
  "allow_facebook_login": false,
  "allow_google_login": false,
  "two_factor_enabled": false,
  "recovery_codes": "",
  "dont_munge_message_id": false,
  "about_me": "",
  "about_format": "about_html",
  "location": "",
  "website": "",
  "time_pref": "time_relative"
  "profile_privacy": "profile_private",
  "default_message_view": "thread_view",
  "topics_sort_dir": "sort_desc",
  "topic_sort_dir": "sort_asc",
  "messages_sort_dir": "sort_none",
  "expanded_messages_sort_dir": "sort_none",
  "search_sort": "relevance_sort",
  "search_sort_dir": "sort_none"
}

Update User

Updates the authenticated user by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

POST Attributes
email
optional
string

New email address. The user object will be set to user_status_not_confirmed and a confirmation email will be sent out.
password
optional
string

New password.
timezone
optional
string

New timezone.
post_pref
optional
string

Posting preference, user_postpref_html, user_postpref_plain, user_postpref_markdown
per_page_pref
optional
string

Per page display preference, user_per_page_pref20, user_per_page_pref50, user_per_page_pref100, user_per_page_pref_infinite
time_pref
optional
string

How to display times, time_relative, time_absolute
dont_munge_message_id
optional
boolean

Whether to change the message-id of any posted messages
allow_facebook_login
optional
boolean
allow_google_login
optional
boolean
Returns

Returns the user object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid email address). Below are the unique errors to this call.

Additional Errors
bad_request

"invalid email" is returned if the new email address is invalid.
bad_request

"email exists" is returned if the new email address already exists.
bad_request

"password too short" is returend if the password is too short.

Definition

https://api.groups.io/v1/updateuser

Example Request

$ curl "https://api.groups.io/v1/updateuser" \
-u AUTHENTICATION_TOKEN: \
-d email=test@example.com

Example Successful Response

{
  "id": 3,
  "object": "user",
  "created": "2017-07-28T12:30:38.052553032-07:00",
  "updated": "2017-08-15T13:11:56.121635376-07:00",
  "email": "john@smith.com",
  "full_name": "John Smith",
  "user_name": "",
  "timezone": "America/Los_Angeles",
  "status": "user_status_confirmed",
  "profile_photo_id": "",
  "has_profile_photo": false,
  "post_pref": "user_postpref_markdown",
  "per_page_pref": "user_per_page_pref20",
  "allow_facebook_login": false,
  "allow_google_login": false,
  "two_factor_enabled": false,
  "recovery_codes": "",
  "dont_munge_message_id": false,
  "about_me": "",
  "about_format": "about_html",
  "location": "",
  "website": "",
  "time_pref": "time_relative",
  "profile_privacy": "profile_private",
  "default_message_view": "thread_view",
  "topics_sort_dir": "sort_desc",
  "topic_sort_dir": "sort_asc",
  "messages_sort_dir": "sort_none",
  "expanded_messages_sort_dir": "sort_none",
  "search_sort": "relevance_sort",
  "search_sort_dir": "sort_none"
}

Example Error Response

    {
      "object": "error",
      "type": "invalid_email",
      "extra": ""
    }

Get Subscriptions

Get the subscriptions associated with the user represented by the authentication token. Subscriptions are returned using the pagination request and object format. Note: these subscriptions are subscription_plus objects, containing extra data as detailed in that object.

Query Parameters
limit
optional
default is 10

A limit on the number of objects to be returned, between 1 and 100.
page_token
optional
opaque

A cursor for use in pagination. To fetch the next page, set page_token to the value of the next_page_token response.
sort_field
optional
string

The field to sort on. Can be full_name, email, delivery, joined.
sort_dir
optional
string

Sort direction. Can be 'asc' or 'desc'.

Definition

https://api.groups.io/v1/getsubs

Example Request

$ curl "https://api.groups.io/v1/getsubs?limit=2&page_token=1" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
  "object": "list",
  "total_count": 2,
  "start_item": 1,
  "end_item": 2,
  "has_more": false,
  "next_page_token": 0,
  "data": [
    {
      "id": 50,
      "object": "subscription_plus",
      "created": "2017-08-07T21:32:07.757486408-07:00",
      "updated": "2017-08-15T13:11:56.114230103-07:00",
      "user_id": 3,
      "group_id": 7,
      "status": "sub_status_normal",
      "post_status": "sub_poststatus_normal",
      "email_delivery": "email_delivery_single",
      "message_selection": "message_selection_all",
      "auto_follow_replies": false,
      "max_attachment_size": "max_attachment_size_unlimited",
      "approved_posts": 0,
      "mod_status": "sub_modstatus_owner",
      "pending_msg_notify": "sub_notify_email",
      "pending_sub_notify": "sub_notify_email",
      "sub_notify": "sub_notify_email",
      "storage_notify": "sub_notify_email",
      "sub_group_notify": "sub_notify_email",
      "message_report_notify": "sub_notify_email",
      "mod_permissions": "",
      "owner_msg_notify": "sub_ownermsg_notify_subs",
      "email": "john@smith",
      "user_status": "user_status_confirmed",
      "user_name": "",
      "timezone": "America/Los_Angeles",
      "full_name": "John Smith",
      "about_me": "",
      "about_format": "about_html",
      "location": "",
      "website": "",
      "profile_photo_id": "",
      "profile_privacy": "profile_private",
      "dont_munge_message_id": false,
      "moderator_notes": "",
      "moderator_notes_updated": "0001-01-01T00:00:00Z",
      "use_signature": false,
      "use_signature_email": false,
      "num_subs": 1,
      "pending_messages": 0,
      "pending_subs": 0,
      "most_recent_message": "1969-12-31T16:00:00-08:00"
    },
    {
      "id": 8,
      "object": "subscription_plus",
      "created": "2017-08-03T10:08:18.604810243-07:00",
      "updated": "2017-08-15T13:11:56.10748515-07:00",
      "user_id": 3,
      "group_id": 4,
      "status": "sub_status_normal",
      "post_status": "sub_poststatus_normal",
      "email_delivery": "email_delivery_single",
      "message_selection": "message_selection_all",
      "auto_follow_replies": false,
      "max_attachment_size": "max_attachment_size_unlimited",
      "approved_posts": 0,
      "mod_status": "sub_modstatus_owner",
      "pending_msg_notify": "sub_notify_email",
      "pending_sub_notify": "sub_notify_email",
      "sub_notify": "sub_notify_email",
      "storage_notify": "sub_notify_email",
      "sub_group_notify": "sub_notify_email",
      "message_report_notify": "sub_notify_email",
      "mod_permissions": "",
      "owner_msg_notify": "sub_ownermsg_notify_subs",
      "email": "john@smith",
      "user_status": "user_status_confirmed",
      "user_name": "",
      "timezone": "America/Los_Angeles",
      "full_name": "John Smith",
      "about_me": "",
      "about_format": "about_html",
      "location": "",
      "website": "",
      "profile_photo_id": "",
      "profile_privacy": "profile_private",
      "dont_munge_message_id": false,
      "moderator_notes": "",
      "moderator_notes_updated": "0001-01-01T00:00:00Z",
      "use_signature": false,
      "use_signature_email": false,
      "num_subs": 91,
      "pending_messages": 0,
      "pending_subs": 0,
      "most_recent_message": "2016-01-31T10:24:16-08:00"
    }
  ]
}

Get Subscription

Get a subscription to a single group.

Query Parameters
group_id
required

ID of the group

Definition

https://api.groups.io/v1/getsub

Example Request

$ curl "https://api.groups.io/v1/getsub?group_id=2" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
  "id": 1,
  "name": "Group1",
  "group_id": 2,
  "mod_status": "sub_modstatus_none",
  "post_status": "sub_poststatus_normal",
  "email_delivery": "email_delivery_single",
  "pending_messages": 0,
  "pending_subs": 0,
}

Update Subscription - NI

Updates a subscription by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

POST Attributes
sub_id
required
number

Subscription ID
Returns

Returns the subscription object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid parameter). Below are the unique errors to this call.

Additional Errors

Definition

https://api.groups.io/v1/updatesub

Example Request

$ curl "https://api.groups.io/v1/updatesub" \
-u AUTHENTICATION_TOKEN: \
-d sub_id=2 \
-d email_delivery=email_delivery_single

Example Error Response

    {
      "object": "error",
      "type": "inadequate_permissions",
      "extra": ""
    }

Delete Subscription - NI

Delete a subscription.

POST Attributes
sub_id
required

ID of the subscription to delete

Definition

https://api.groups.io/v1/delsub

Example Request

$ curl "https://api.groups.io/v1/delsub" \
-u AUTHENTICATION_TOKEN: \
-d sub_id=2

Example Error Response

    {
      "object": "error",
      "type": "inadequate_permissions",
      "extra": ""
    }

Join Group - NI

Join a group

Query Parameters
group_id
required

ID of the group to join
Successful Response Attributes
TBD

Definition

https://api.groups.io/v1/joingroup

Example Request

$ curl "https://api.groups.io/v1/joingroup?group_id=2" \
-u AUTHENTICATION_TOKEN:

Successful Response

HTTP 200

Example Error Response

    {
      "object": "error",
      "type": "inadequate_permissions",
      "extra": ""
    }

Group

Actions involving a specific group.

Get Permissions

Get a subscription's permissions. Each subscription grants a set of permissions in a group. The permissions are determined by a whether a subscription is a normal user, a moderator, or an owner, as well as the various group settings. Note: you do not need to be subscribed to the group.

Permissions Needed

None.

Query Parameters
group_id
required
number

ID of the group

Definition

https://api.groups.io/v1/getperms

Example Request

$ curl "https://api.groups.io/v1/getperms?group_id=7" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
  "object": "permissions",
  "manage_subgroups": true,
  "delete_group": true,
  "view_archives": true,
  "download_members": true,
  "view_activity": true,
  "manage_hashtags": true,
  "manage_integrations": true,
  "manage_group_settings": true,
  "make_moderator": true,
  "manage_member_subscription_options": true,
  "manage_pending_members": true,
  "remove_members": true,
  "ban_members": true,
  "manage_group_billing": true,
  "edit_archives": true,
  "manage_pending_messages": true,
  "invite_members": true,
  "view_databases": true,
  "can_post": true,
  "manage_polls": true,
  "view_photos": true,
  "manage_photos": true,
  "manage_members": true,
  "view_calendar": true,
  "manage_calendar": true,
  "view_chats": true,
  "manage_chats": true,
  "view_member_directory": true,
  "view_files": true,
  "manage_files": true,
  "view_members": true,
  "view_wiki": true,
  "manage_wiki": true,
  "manage_subscription": true
}

Example Error Response

    {
      "object": "error",
      "type": "bad_request",
      "extra": ""
    }

Create A Sub Group - NI

Create a subgroup.

Permissions Needed

You must have the manage_subgroups permission to use this call.

Query Parameters
group_id
required
number

ID of the parent group
subgroupname
required
string

Name of the new subgroup
desc
required
string

Description of the new subgroup
privacy
required
string

Privacy of the new subgroup, one of sub_group_privacy_limited_archives, sub_group_privacy_archives, sub_group_privacy_unlisted, sub_group_privacy_none
Possible Error Responses
invalid_groupname

The subgroup name is invalid.
description_too_short

The subgroup description is too short.
name_already_taken

A subgroup with that name already exists.

Definition

https://api.groups.io/v1/createsubgroup

Example Request

$ curl "https://api.groups.io/v1/createsubgroup?group_id=7&subgroupname=NewGroup&desc=This+is+my+subgroup&privacy=listed/parent" \
-u AUTHENTICATION_TOKEN:

Successful Response

HTTP 200

Example Error Response

    {
      "object": "error",
      "type": "inadequate_permissions",
      "extra": ""
    }

Get Group Settings

Get the group settings

Permissions Needed

You must have the manage_group_settings permission to use this call.

Query Parameters
group_id
required
number

ID of the group

Definition

https://api.groups.io/v1/getgroup

Example Request

$ curl "https://api.groups.io/v1/getgroup?group_id=7" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
  "id": 5,
  "object": "group",
  "created": "2017-08-03T10:18:15.218974479-07:00",
  "updated": "2017-08-15T12:48:41.965409169-07:00",
  "title": "",
  "parent_group_id": 0,
  "name": "test",
  "alias": "main",
  "desc": "This is a description of a test group.",
  "subject_tag": "[test]",
  "footer": "This is my\r\nFooter!!!!",
  "website": "",
  "announce": false,
  "moderated": false,
  "new_users_moderated": true,
  "unmoderate_users_after": 1,
  "restricted": false,
  "allow_non_subs_to_post": false,
  "force_html_emails": false,
  "normalize_html_emails": false,
  "reply_to": "group_reply_to_group",
  "remove_other_reply_options": false,
  "privacy": "group_privacy_none",
  "members_visible": "group_view_members_subs",
  "subgroup_access": "sub_group_subs",
  "calendar_access": "group_access_limited",
  "files_access": "group_access_limited",
  "database_access": "group_access_limited",
  "wiki_access": "group_access_limited",
  "photos_access": "group_access_limited",
  "member_directory_access": "group_access_limited",
  "polls_access": "polls_access_subscribers",
  "chat_access": "group_access_limited",
  "handle_attachments": "group_attachments_normal",
  "plain_text_only": false,
  "max_photo_size_email": "max_photo_size_none",
  "max_photo_size_photos": "max_photo_size_none",
  "max_photo_size_databases": "max_photo_size_none",
  "max_photo_size_wiki_images": "max_photo_size_none",
  "hash_tags_required": false,
  "restrict_create_hash_tags": false,
  "bounce_attachments": false,
  "allow_photos_in_files": false,
  "email_delivery_default": "email_delivery_none",
  "message_selection_default": "message_selection_all",
  "auto_follow_replies_default": true,
  "max_attachment_size_default": "max_attachment_size_unlimited",
  "disable_edits": false,
  "disable_no_email": false,
  "auto_close_threads": false,
  "close_threads_after": 0,
  "auto_moderate_threads": false,
  "moderate_threads_after": 0
}

Get Subgroups

Get a group's subgroups.

Permissions Needed

You must have the manage_group_settings permission to use this call.

Query Parameters
group_id
required
number

ID of the parent group
limit
optional
default is 10

A limit on the number of objects to be returned, between 1 and 100.
page_token
optional
opaque

A cursor for use in pagination. To fetch the next page, set page_token to the value of the next_page_token response.
sort_field
optional
string

The field to sort on. Can be created, name.
sort_dir
optional
string

Sort direction. Can be 'asc' or 'desc'.

Definition

https://api.groups.io/v1/getsubgroups

Example Request

$ curl "https://api.groups.io/v1/getsubgroups?group_id=5" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
  "object": "list",
  "total_count": 1,
  "start_item": 1,
  "end_item": 1,
  "has_more": false,
  "next_page_token": 0,
  "data": [
    {
      "id": 8,
      "object": "group",
      "created": "2017-08-07T21:33:32.851703356-07:00",
      "updated": "2017-08-15T12:48:41.986378376-07:00",
      "title": "",
      "parent_group_id": 5,
      "name": "beta+first",
      "alias": "",
      "desc": "",
      "subject_tag": "[first]",
      "footer": "",
      "website": "",
      "announce": false,
      "moderated": false,
      "new_users_moderated": false,
      "unmoderate_users_after": 0,
      "restricted": false,
      "allow_non_subs_to_post": false,
      "force_html_emails": false,
      "normalize_html_emails": false,
      "reply_to": "group_reply_to_group",
      "remove_other_reply_options": false,
      "privacy": "sub_group_privacy_unlisted",
      "members_visible": "group_view_members_moderators",
      "subgroup_access": "sub_group_subs",
      "calendar_access": "group_access_limited",
      "files_access": "group_access_limited",
      "database_access": "group_access_limited",
      "wiki_access": "group_access_limited",
      "photos_access": "group_access_limited",
      "member_directory_access": "group_access_limited",
      "polls_access": "polls_access_subscribers",
      "chat_access": "group_access_limited",
      "handle_attachments": "group_attachments_normal",
      "plain_text_only": false,
      "max_photo_size_email": "max_photo_size_none",
      "max_photo_size_photos": "max_photo_size_none",
      "max_photo_size_databases": "max_photo_size_none",
      "max_photo_size_wiki_images": "max_photo_size_none",
      "hash_tags_required": false,
      "restrict_create_hash_tags": false,
      "bounce_attachments": false,
      "allow_photos_in_files": false,
      "email_delivery_default": "email_delivery_single",
      "message_selection_default": "message_selection_all",
      "auto_follow_replies_default": false,
      "max_attachment_size_default": "max_attachment_size_unlimited",
      "disable_edits": false,
      "disable_no_email": false,
      "auto_close_threads": false,
      "close_threads_after": 0,
      "auto_moderate_threads": false,
      "moderate_threads_after": 0
    }
  ]
}

Update Group

Update a group's settings.

Permissions Needed

You must have the manage_group_settings permission to use this call.

POST Parameters
group_id
required
number

ID of the group
title
optional
string

Title.
name
optional
string

Name.
alias
optional
string

Alias.
desc
optional
string

Description.
subject_tag
optional
string

Subject tag.
footer
optional
string

Message footer.
website
optional
string

Website.
announce
optional
boolean
moderated
optional
boolean
new_users_moderated
optional
boolean
unmoderate_users_after
optional
number
restricted
optional
boolean
allow_non_subs_to_post
optional
boolean
force_html_emails
optional
boolean
normalize_html_emails
optional
boolean
reply_to
optional
string

Can be group_reply_to_group, group_reply_to_sender, group_reply_to_moderators, group_reply_to_group_and_sender
remove_other_reply_options
optional
boolean
privacy
optional
string

For a parent/stand alone group, can be group_privacy_none, group_privacy_archives, group_privacy_unlisted, group_privacy_unlisted_public.

For a subgroup, can be sub_group_privacy_limited_archives, sub_group_privacy_archives, sub_group_privacy_unlisted, sub_group_privacy_none.
members_visible
optional
string

Can be group_view_members_subs, group_view_members_moderators, group_view_members_owners
subgroup_access
optional
string

Can be sub_group_subs, sub_group_moderators, sub_group_owners
calendar_access
optional
string

Can be group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited
files_access
optional
string

Can be group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none
database_access
optional
string

Can be group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none
wiki_access
optional
string

Can be group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited
photos_access
optional
string

Can be group_access_limited, group_access_subscribers, group_access_moderators_only, group_access_none
member_directory_access
optional
string

Can be group_access_limited, group_access_moderators_only, group_access_none
polls_access
optional
string

Can be polls_access_subscribers, polls_access_limited, polls_access_none
chat_access
optional
string

Can be group_access_limited, group_access_subscribers, group_access_none
handle_attachments
optional
string

Can be group_attachments_normal, group_attachments_bounced, group_attachments_stripped
plain_text_only
optional
boolean
max_photo_size_email
optional
string

Can be max_photo_size_none, max_photo_size_small, max_photo_size_medium, max_photo_size_large, max_photo_size_ex_small, max_photo_size_medium_small, max_photo_size_somewhat_small
max_photo_size_photos
optional
string

Can be max_photo_size_none, max_photo_size_small, max_photo_size_medium, max_photo_size_large, max_photo_size_ex_small, max_photo_size_medium_small, max_photo_size_somewhat_small
max_photo_size_databases
optional
string

Can be max_photo_size_none, max_photo_size_small, max_photo_size_medium, max_photo_size_large, max_photo_size_ex_small, max_photo_size_medium_small, max_photo_size_somewhat_small
max_photo_size_wiki_images
optional
string

Can be max_photo_size_none, max_photo_size_small, max_photo_size_medium, max_photo_size_large, max_photo_size_ex_small, max_photo_size_medium_small, max_photo_size_somewhat_small
hash_tags_required
optional
boolean
restrict_create_hash_tags
optional
boolean
bounce_attachments
optional
boolean
allow_photos_in_files
optional
boolean
email_delivery_default
optional
string

Email delivery default, can be email_delivery_single, email_delivery_digest, email_delivery_special, email_delivery_none, email_delivery_html_digest, email_delivery_summary
message_selection_default
optional
string

Message selection, can be message_selection_all, message_selection_follow_only, message_selection_follow_and_first_message
auto_follow_replies_default
optional
boolean
max_attachment_size_default
optional
string

Maximum attachment size, can be max_attachment_size_unlimited, max_attachment_size_small, max_attachment_size_medium, max_attachment_size_large, max_attachment_size_none
disable_edits
optional
boolean
disable_no_email
optional
boolean
auto_close_threads
optional
boolean
close_threads_after
optional
number
auto_moderate_threads
optional
boolean
moderate_threads_after
optional
number
Notes
  • A stand alone/parent group cannot have all the fields announce, restricted, moderated, and new_users_moderated all set to false. If you do this, new_users_moderated will automatically be set to true.
  • A stand alone/parent group with private archives cannot later be switched to having public archives.
  • A subgroup with archives that are private to the subgroup cannot be later switched to either public archives or to archives that are viewable by the parent group.
  • If disable_no_email is changed to true, any member subscriptions that were set to email_delivery_none will automatically be changed to email_delivery_special. Also if email_delivery_default is set to email_delivery_none, it will be changed to email_delivery_special.
  • If force_html_emails is changed to true, any member subscriptions that were set to email_delivery_digest will automatically be changed to email_delivery_html_digest. Also if email_delivery_default is set to email_delivery_digest, it will be changed to email_delivery_html_digest.
  • If a group has alias set, that field cannot be unset/set to blank.
  • If this is a subgroup, the name field has to be of the form ParentGroupName+SubGroupName.
Returns

Returns the group object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
bad_request

"name exists" is returned if the group name is already taken.
bad_request

"invalid groupname" is returned if it's a bad group name.

Definition

https://api.groups.io/v1/updategroup

Example Request

$ curl "https://api.groups.io/v1/updategroup" \
-u AUTHENTICATION_TOKEN: \
-d group_id=2 \
-d chat_access=group_access_limited

Example Error Response

    {
      "object": "error",
      "type": "inadequate_permissions",
      "extra": ""
    }

Delete Group - NI

Delete a group or a subgroup.

Permissions Needed

You must have the delete_group permission to use this call.

Query Parameters
group_id
required
number

ID of the group

Definition

https://api.groups.io/v1/delgroup

Example Request

$ curl "https://api.groups.io/v1/delgroup?group_id=7" \
-u AUTHENTICATION_TOKEN:

Successful Response

HTTP 200

Example Error Response

    {
      "object": "error",
      "type": "inadequate_permissions",
      "extra": ""
    }

Members

Actions involving the members of a group.

Get Members

Get the members of a group. Each member is represented by a subscription. Subscriptions are returned using the pagination request and object format.

Permissions Needed

You must have the view_members permission to use this call.

Query Parameters
group_id
required
number

ID of the group
type
optional
default is members

The type of member to be returned, can be pending, banned, mods, members. See Notes for restrictions.
limit
optional
default is 10

A limit on the number of objects to be returned, between 1 and 100.
page_token
optional
opaque

A cursor for use in pagination. To fetch the next page, set page_token to the value of the next_page_token response.
sort_field
optional
string

The field to sort on. Can be full_name, email, delivery, joined.
sort_dir
optional
string

Sort direction. Can be 'asc' or 'desc'.
Notes
  • If you do not have the manage_pending_members permission, you cannot specify the type pending.
  • If you do not have the ban_members permission, you cannot specify the type banned.

Definition

https://api.groups.io/v1/getmembers

Example Request

$ curl "https://api.groups.io/v1/getmembers?group_id=7" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
  "object": "list",
  "total_count": 40,
  "start_item": 1,
  "end_item": 1,
  "has_more": false,
  "next_page_token": 0,
  "data": [
    {
      "id": 701,
      "object": "subscription",
      "created": "2017-08-15T13:58:22.618029196-07:00",
      "updated": "2017-08-15T13:58:22.618029196-07:00",
      "user_id": 147,
      "group_id": 4,
      "status": "sub_status_normal",
      "post_status": "sub_poststatus_normal",
      "email_delivery": "email_delivery_single",
      "message_selection": "message_selection_all",
      "auto_follow_replies": false,
      "max_attachment_size": "max_attachment_size_small",
      "approved_posts": 0,
      "mod_status": "sub_modstatus_none",
      "pending_msg_notify": "sub_notify_email",
      "pending_sub_notify": "sub_notify_email",
      "sub_notify": "sub_notify_email",
      "storage_notify": "sub_notify_email",
      "sub_group_notify": "sub_notify_email",
      "message_report_notify": "sub_notify_email",
      "mod_permissions": "",
      "owner_msg_notify": "sub_ownermsg_notify_subs",
      "email": "john@smith.com",
      "user_status": "user_status_confirmed",
      "user_name": "",
      "timezone": "",
      "full_name": "John Smith",
      "about_me": "",
      "about_format": "about_html",
      "location": "",
      "website": "",
      "profile_photo_id": "",
      "profile_privacy": "profile_private",
      "dont_munge_message_id": false,
      "moderator_notes": "",
      "moderator_notes_updated": "1969-12-31T16:00:00-08:00",
      "use_signature": false,
      "use_signature_email": false
    }
  ]
}

Get Member

Get a member of a group. A member is represented by a subscription.

Permissions Needed

You must have the view_members permission to use this call.

Query Parameters
group_id
required
number

ID of the group
sub_id
required
number

ID of the member subscription

Definition

https://api.groups.io/v1/getmember

Example Request

$ curl "https://api.groups.io/v1/getmember?group_id=2&sub_id=46" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
    "id": 46,
    "object": "subscription",
    "created": "2017-08-03T10:20:02.713284878-07:00",
    "updated": "2017-08-03T10:20:02.765893519-07:00",
    "user_id": 39,
    "group_id": 5,
    "status": "sub_status_normal",
    "post_status": "sub_poststatus_normal",
    "email_delivery": "email_delivery_single",
    "message_selection": "message_selection_all",
    "auto_follow_replies": false,
    "max_attachment_size": "max_attachment_size_small",
    "approved_posts": 0,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "",
    "owner_msg_notify": "sub_ownermsg_notify_subs",
    "email": "example@yahoo.com",
    "user_status": "user_status_confirmed",
    "user_name": "beta1.user35",
    "timezone": "",
    "full_name": "example1",
    "about_me": "",
    "about_format": "about_html",
    "location": "",
    "website": ""
}

Search Members

Search the members of a group. The search is over email addresses and full names. Each member is represented by a subscription. Subscriptions are returned using the pagination request and object format.

Permissions Needed

You must have the view_members permission to use this call.

Query Parameters
group_id
required
number

ID of the group
q
required
string

Email or name fragment to search on.
limit
optional
default is 10

A limit on the number of objects to be returned, between 1 and 100.
page_token
optional
opaque

A cursor for use in pagination. To fetch the next page, set page_token to the value of the next_page_token response.
sort_field
optional
string

The field to sort on. Can be full_name, email, delivery, joined.
sort_dir
optional
string

Sort direction. Can be 'asc' or 'desc'.

Definition

https://api.groups.io/v1/searchmembers

Example Request

$ curl "https://api.groups.io/v1/searchmembers?group_id=7&q=smith.com" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

{
  "object": "list",
  "total_count": 40,
  "start_item": 1,
  "end_item": 1,
  "has_more": false,
  "next_page_token": 0,
  "data": [
    {
      "id": 701,
      "object": "subscription",
      "created": "2017-08-15T13:58:22.618029196-07:00",
      "updated": "2017-08-15T13:58:22.618029196-07:00",
      "user_id": 147,
      "group_id": 4,
      "status": "sub_status_normal",
      "post_status": "sub_poststatus_normal",
      "email_delivery": "email_delivery_single",
      "message_selection": "message_selection_all",
      "auto_follow_replies": false,
      "max_attachment_size": "max_attachment_size_small",
      "approved_posts": 0,
      "mod_status": "sub_modstatus_none",
      "pending_msg_notify": "sub_notify_email",
      "pending_sub_notify": "sub_notify_email",
      "sub_notify": "sub_notify_email",
      "storage_notify": "sub_notify_email",
      "sub_group_notify": "sub_notify_email",
      "message_report_notify": "sub_notify_email",
      "mod_permissions": "",
      "owner_msg_notify": "sub_ownermsg_notify_subs",
      "email": "john@smith.com",
      "user_status": "user_status_confirmed",
      "user_name": "",
      "timezone": "",
      "full_name": "John Smith",
      "about_me": "",
      "about_format": "about_html",
      "location": "",
      "website": "",
      "profile_photo_id": "",
      "profile_privacy": "profile_private",
      "dont_munge_message_id": false,
      "moderator_notes": "",
      "moderator_notes_updated": "1969-12-31T16:00:00-08:00",
      "use_signature": false,
      "use_signature_email": false
    }
  ]
}

Update Member

Change a member's subscription.

Permissions Needed

You must have the manage_member_subscription_options permission to use this call, in addition to any permissions specified below.

POST Parameters
group_id
required
number

ID of the group.
sub_id
required
number

ID of the subscription.
post_status
optional
string

Posting status, can be sub_poststatus_normal, sub_poststatus_allowed, sub_poststatus_moderated, sub_poststatus_notallowed, sub_poststatus_newusermoderated
email_delivery
optional
string

Email delivery, can be email_delivery_single, email_delivery_digest, email_delivery_special, email_delivery_none, email_delivery_html_digest, email_delivery_summary
message_selection
optional
string

Message selection, can be message_selection_all, message_selection_follow_only, message_selection_follow_and_first_message
auto_follow_replies
optional
boolean
max_attachment_size
optional
string

Maximum attachment size, can be max_attachment_size_unlimited, max_attachment_size_small, max_attachment_size_medium, max_attachment_size_large, max_attachment_size_none
full_name
optional
string
moderator_notes
optional
string
You must have the `make_moderator` permission in order to set these fields
mod_status
optional
string

Moderator status, can be sub_modstatus_none, sub_modstatus_moderator, sub_modstatus_owner
mod_permissions
optional
string

Moderator permissions, comma separated list of zero or more of the following: sub_perm_pendingmsgs, sub_perm_pendingmembers, sub_perm_invitemembers, sub_perm_removemembers, sub_perm_banmembers, sub_perm_makemoderator, sub_perm_createhashtags, sub_perm_groupsettings, sub_perm_modsub, sub_perm_integrations, sub_perm_editarchives, sub_perm_billing, sub_perm_managesubgroups
pending_msg_notify
optional
string

Notify about pending messages, can be sub_notify_email, sub_notify_none
pending_sub_notify
optional
string

Notify about pending subscriptions, can be sub_notify_email, sub_notify_none
sub_notify
optional
string

Notify when someone joins the group, can be sub_notify_email, sub_notify_none
storage_notify
optional
string

Notify when storage limits are reached, can be sub_notify_email, sub_notify_none
sub_group_notify
optional
string

Notify when a subgroup is created, can be sub_notify_email, sub_notify_none
message_report_notify
optional
string

Notify when someone reports a message, can be sub_notify_email, sub_notify_none
owner_msg_notify
optional
string

Receive messages sent to the +owner address, can be sub_ownermsg_notify_all, sub_ownermsg_notify_subs, sub_ownermsg_notify_none
Returns

Returns the subscription object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
"bad_request"

"no owners" is returned if changing the mod_status field will leave the group without any owners.

Definition

https://api.groups.io/v1/updatemember

Example Request

$ curl "https://api.groups.io/v1/updatemember" \
-u AUTHENTICATION_TOKEN: \
-d group_id=1 \
-d sub_id=2 \
-d post_status=sub_poststatus_allowed

Example Error Response

    {
      "object": "error",
      "type": "invalid_value",
      "extra": "mod_permission"
    }

Send a Bounce Probe

Send a bounce probe.

Permissions Needed

You must have the manage_member_subscription_options permission to use this call.

POST Parameters
group_id
required
number

ID of the group.
sub_id
required
number

ID of the subscription.
Returns

Returns the subscription object. Returns an error if update parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
bad_request

"user not bouncing" is returned if the member's user_status is not either user_status_bouncing and user_status_bounced

Definition

https://api.groups.io/v1/sendbounceprobe

Example Request

$ curl "https://api.groups.io/v1/sendbounceprobe" \
-u AUTHENTICATION_TOKEN: \
-d group_id=1 \
-d sub_id=2 \

Example Error Response

    {
      "object": "error",
      "type": "invalid_value",
      "extra": "mod_permission"
    }

Send a Confirmation Email

Send a confirmation email.

Permissions Needed

You must have the manage_member_subscription_options permission to use this call.

POST Parameters
group_id
required
number

ID of the group.
sub_id
required
number

ID of the subscription.
Returns

Returns the subscription object. Returns an error if parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
bad_request

"user not unconfirmed" is returned if the member's user_status is not user_status_not_confirmed

Definition

https://api.groups.io/v1/sendconfirmation

Example Request

$ curl "https://api.groups.io/v1/sendconfirmation" \
-u AUTHENTICATION_TOKEN: \
-d group_id=1 \
-d sub_id=2 \

Example Error Response

    {
      "object": "error",
      "type": "invalid_value",
      "extra": "mod_permission"
    }

Ban Member

Ban this member.

Permissions Needed

You must have the ban_members permission to use this call.

POST Parameters
group_id
required
number

ID of the group.
sub_id
required
number

ID of the subscription.
Returns

Returns the subscription object if the ban succeeded. Returns an error if parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
bad_request

"user already banned" is returned if the member's status is already sub_status_banned
bad_request

"member cannot be a moderator or owner" is returned if the member's mod_status is not sub_modstatus_none

Definition

https://api.groups.io/v1/banmember

Example Request

$ curl "https://api.groups.io/v1/banmember" \
-u AUTHENTICATION_TOKEN: \
-d group_id=1 \
-d sub_id=2 \

Example Error Response

    {
      "object": "error",
      "type": "invalid_value",
      "extra": "mod_permission"
    }

Approve Pending Member

Approve a pending member.

Permissions Needed

You must have the manage_pending_members permission to use this call.

POST Parameters
group_id
required
number

ID of the group.
sub_id
required
number

ID of the subscription.
Returns

Returns the subscription object if the approval succeeded. Returns an error if parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
Notes
  • The active Welcome member notice will be sent to the member, if there is one.
  • A subscription notification will be sent to all owners/moderators with that notification enabled.

Definition

https://api.groups.io/v1/approvemember

Example Request

$ curl "https://api.groups.io/v1/approvemember" \
-u AUTHENTICATION_TOKEN: \
-d group_id=1 \
-d sub_id=2 \

Example Error Response

    {
      "object": "error",
      "type": "invalid_value",
      "extra": "mod_permission"
    }

Remove Member

Remove a member from a group.

Permissions Needed

You must have the remove_members permission to use this call.

POST Parameters
group_id
required
number

ID of the group.
sub_id
required
number

ID of the subscription.
Returns

Returns an error if parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
Notes
  • If the member's status is sub_status_pending, the active Rejected Subscription member notice will be sent to the member, if there is one.
  • If the member's status is sub_status_normal, the active Removed Member notice will be sent to the member, if there is one.
  • If the member's status is sub_status_banned, no member notices will be sent out.

Definition

https://api.groups.io/v1/removemember

Example Request

$ curl "https://api.groups.io/v1/removemember" \
-u AUTHENTICATION_TOKEN: \
-d group_id=1 \
-d sub_id=2 \

Example Error Response

    {
      "object": "error",
      "type": "invalid_value",
      "extra": "mod_permission"
    }

Direct Add

Directly add people to a group.

Permissions Needed

You must have the invite_members permission to use this call. In addition, the group must be a Premium or Enterprise group.

POST Parameters
group_id
required
number

ID of the group
emails
required
string

A newline separated list of email addresses to add.
subject
optional
string
message
optional
string
subgroupids
optional
string

A comma separated list of IDs of sub groups to also add these people to.
Returns

Returns a direct add results object if the approval succeeded. Returns an error if parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
bad_request

"basic group" is returned if the group is not a premium or enterprise group.
bad_request

"direct add in subgroup" is returned if the group_id refers to a subgroup and not a main group.
bad_request

"group is not a subgroup" is returned if a group ID in subgroupids refers to a group that is not a subgroup of the group.
pending_adds

Is returned if the adds require approval. The adds will take place once they have been reviewed.
Notes
  • There is a limit to the number of direct adds that can be done to a group per-day. Go over that limit and the pending_adds message will be returned.
  • If a message is specified and there is an active Direct Add member notice, it will be updated with the message.
  • If a message is specified and there is no active Direct Add member notice, one will be created.

Definition

https://api.groups.io/v1/directadd

Example Request

$ curl "https://api.groups.io/v1/directadd" \
-u AUTHENTICATION_TOKEN: \
-d group_id=4 \
-d $'emails=test@example.com\nJohn Smith <john@smith.com>`

Example Successful Response

{
  "object": "direct_add_results",
  "total_emails": 2,
  "errors": [
    {
      "object": "direct_add_error",
      "email": "test@example.com",
      "status": "direct_add_invalid_email"
    }
  ],
  "added_members": [
    {
      "id": 701,
      "object": "subscription",
      "created": "2017-08-15T13:58:22.618029196-07:00",
      "updated": "2017-08-15T13:58:22.618029196-07:00",
      "user_id": 147,
      "group_id": 4,
      "status": "sub_status_normal",
      "post_status": "sub_poststatus_normal",
      "email_delivery": "email_delivery_single",
      "message_selection": "message_selection_all",
      "auto_follow_replies": false,
      "max_attachment_size": "max_attachment_size_small",
      "approved_posts": 0,
      "mod_status": "sub_modstatus_none",
      "pending_msg_notify": "sub_notify_email",
      "pending_sub_notify": "sub_notify_email",
      "sub_notify": "sub_notify_email",
      "storage_notify": "sub_notify_email",
      "sub_group_notify": "sub_notify_email",
      "message_report_notify": "sub_notify_email",
      "mod_permissions": "",
      "owner_msg_notify": "sub_ownermsg_notify_subs",
      "email": "john@smith.com",
      "user_status": "user_status_confirmed",
      "user_name": "",
      "timezone": "",
      "full_name": "John Smith",
      "about_me": "",
      "about_format": "about_html",
      "location": "",
      "website": "",
      "profile_photo_id": "",
      "profile_privacy": "profile_private",
      "dont_munge_message_id": false,
      "moderator_notes": "",
      "moderator_notes_updated": "0001-01-01T00:00:00Z",
      "use_signature": false,
      "use_signature_email": false
    }
  ]
}

Invite

Invite people to join a group.

Permissions Needed

You must have the invite_members permission to use this call.

POST Parameters
group_id
required
number

ID of the group
emails
required
string

A newline separated list of email addresses to invite.
subject
optional
string
message
optional
string
Returns

Returns a invite results object if the approval succeeded. Returns an error if parameters are invalid (e.g. specifying an invalid group name). Below are the unique errors to this call.

Additional Errors
bad_request

"invite in subgroup" is returned if the group_id refers to a subgroup and not a main group.
pending_invites

Is returned if the invites require approval. The invites will take place once they have been reviewed.
Notes
  • There is a limit to the number of invites that can be sent from a group per-day. Go over that limit and the pending_invites message will be returned.
  • If a message is specified and there is an active Invite member notice, it will be updated with the message.
  • If a message is specified and there is no active Invite member notice, one will be created.

Definition

https://api.groups.io/v1/invite

Example Request

$ curl "https://api.groups.io/v1/invite" \
-u AUTHENTICATION_TOKEN: \
-d group_id=4 \
-d $'emails=test@example.com\nJohn Smith <john@smith.com>`

Example Successful Response

{
  "object": "invite_results",
  "total_emails": 2,
  "errors": [
    {
      "object": "invite_error",
      "email": "test@example.com",
      "status": "invite_invalid_email"
    }
  ],
  "invited": [ 
    "john@smith.com", 
    "bob@smith.com" 
  ]
}

Archives

Actions involving message archives.

Get Topics - NI

Get a group's topics. A topic represents one or more messages in a group. Topics are returned using the pagination request and object format.

Permissions Needed

You must have the view_archives permission to use this call.

Query Parameters
group_id
number, required

The ID of the group
limit
optional
default is 10

A limit on the number of objects to be returned, between 1 and 100.
page_token
optional

A cursor for use in pagination. To fetch the next page, set page_token to the value of the next_page_token response.
sort_field
optional
string

The field to sort on. Valid values are dependent on the call.
sort_dir
optional
string

Sort direction. Can be 'asc' or 'desc'.
Successful Response Attributes
id
number

ID of the topic
subject
string

Subject of the topic
snippet
string

Snippet of the first message in the topic
poster
object

Poster of the first message in the topic

name
string

Name of the poster to be displayed
user_id
number

ID of the poster (may be 0)
user_name
string

User name of the post (may be empty)
num_messages
number

The number of messages in the topic
most_recent_message
string

Date of the most recent message
is_sticky
boolean

If the topic is sticky
is_moderated
boolean

If the topic is moderated
is_cloed
boolean

If the topic is closed
hashtags
array

Array of hashtags

id
number

ID of the hashtag
name
string

Name of the hashtag
color
string

Hex color of the hashtag

Definition

https://api.groups.io/v1/gettopics

Example Request

$ curl "https://api.groups.io/v1/gettopics?group_id=3&limit=2&page_token=1" \
-u AUTHENTICATION_TOKEN:

Example Successful Response

    {
      "has_more": true,
      "next_page_token": 3,
      "start_item": 3,
      "end_item": 10,
      "total_count": 20,
      "data": [
        {
          "id": 2,
          "subject": "This is the topic subject for group 3, topic 2",
          "snippet": "This is the snippet for group 3, topic 2",
          "poster": {
            "name": "john smith",
            "user_id": 123
          },
          "num_msgs": 1,
          "most_recent_message": "2017-04-17T15:17:48.236424628-07:00",
          "is_sticky": false,
          "is_moderated": false,
          "is_closed": false,
          "hashtags": [
            {
              "id": 1,
              "name": "Hashtag0",
              "color": "61b16c"
            }
          ]
        },
        {
          "id": 3,
          "subject": "This is the topic subject for group 3, topic 3",
          "snippet": "This is the snippet for group 3, topic 3",
          "poster": {
            "name": "markf@"
          },
          "num_msgs": 2,
          "most_recent_message": "2017-01-18T15:17:48.236427663-08:00",
          "is_sticky": false,
          "is_moderated": false,
          "is_closed": false,
          "hashtags": [
            {
              "id": 1,
              "name": "Hashtag0",
              "color": "61b16c"
            },
            {
              "id": 2,
              "name": "Hashtag1",
              "color": "faa849"
            }
          ]
        }
      ]
    }