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 Endpoints

The endpoint for accessing all groups a person is subscribed to is groups.io/api. If a person is subscribed to one or more enterprise groups, accessing just those groups can be done through the enterprise domain.

Versioning And Change Log

NOTE During development, we sometimes need to make backwards incompatible changes. If this happens during development, we will not be changing API versions.

View the changelog to see changes between different versions.

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.

Success

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, some endpoints need to return additional information on success. In these instances, a success object is returned with the additional information. This object is returned with the HTTP 200 response code.

Response Attributes
object
string, value is "success"

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

Extra information, endpoint specific.

Example Success Response

    {
      "object": "success",
      "extra": "pending post"
    }

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_error

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.
bad_csrf

The endpoint required a valid csrf parameter. The parameter was either missing or incorrect.
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": ""
    }

Extended Return Information

Many endpoints support the extended=true parameter. When this is specified, additional information is returned from the endpoint. The default return for an endpoint is a JSON object, as specified in the documentation. When the extended=true parameter is set, instead a two element JSON array is returned. One element of the array is the original return object. The second element is a User Object.

Libraries

The following are unofficial libraries.

JAVA

github.com/lake54/groupsio-api-java

Authentication

Authentication

Authentication to the API is performed via either HTTP cookies using cookies set from the login API call, which is the default, or via HTTP Basic Auth, using a token received from the login API call when passing in the token parameter. Note, some endpoints, like /facebooklogin, /googlelogin and the chat endpoints require or institute cookie login. All curl examples in the documentation assume cookie authentication.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Activity Log

Get Activity Log

Get activity log entries. Entries are returned using the pagination request and object format.

Permissions Needed

You must have the view_activity permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
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 "id" and "created".
sort_dir
optional
string

Sort direction. Can be asc or desc.
filter_by
optional
string

Type of log to filter by, can be: member, message, mod, pay.
restrict_date
optional
string

Time period to restrict results by, can be: today, last_week, last_30_days, before, after, between.
start_date
optional
string

Start time of the time period specified by restrict_date values of after, between.
end_date
optional
string

Start time of the time period specified by restrict_date values of between, between.
action
optional
string

Restrict results to a single activity type.
member_info_id
optional
number

Restrict results to the member.
past_member_info_id
optional
number

Restrict results to the past member.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a Activity Log list object if successful. Returns an error if there is an error.

Additional Errors
"bad_request"

"invalid filter_by" is returned if the filter_by value is invalid.
"bad_request"

"invalid restrict_date" is returned if the restrict_date value is invalid.
"bad_request"

"invalid action" is returned if the action value is invalid.
"bad_request"

"invalid start_date" is returned if the start_date value is invalid.
"bad_request"

"invalid end_date" is returned if the end_date value is invalid.

GET /api/v1/getactivitylog

$ curl "https://groups.io/api/v1/getactivitylog?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 81,
 "start_item": 87,
 "end_item": 47,
 "has_more": false,
 "next_page_token": 59,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 81,
    "object": "activity_log",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 18,
    "entry": "",
    "via": "via_api",
   }
 ],
}
View Activity Log List definition

Example Error Response

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

Archives

These endpoints deal with the message archives. The archives consist of messages, which are grouped into topics.

Get Topics

Get a group's topics or a user'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 archives_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name can be specified. If neither is specified, a user's set of groups is used.
group_name
required
string

Name of the group. Either group_id or group_name can be specified. If neither is specified, a user's set of groups is used.
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.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

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

Additional Errors
No additional errors

GET /api/v1/gettopics

$ curl "https://groups.io/api/v1/gettopics?groupid=2" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 25,
 "start_item": 40,
 "end_item": 56,
 "has_more": false,
 "next_page_token": 0,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "group_perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "group": 
   {
    "id": 94,
    "object": "group",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "title": "The Example Group",
    "name": "example",
    "nice_group_name": "",
    "alias": "",
    "desc": "This is the description for the example group.",
    "plain_desc": "This is the description for the example group.",
    "subject_tag": "[example]",
    "footer": "",
    "website": "",
    "announce": false,
    "moderation": "moderate_first_message",
    "new_users_moderated": false,
    "unmoderate_users_after": 11,
    "restricted": false,
    "allow_non_subs_to_post": false,
    "force_html_emails": false,
    "normalize_html_emails": false,
    "reply_to": "group_reply_only_to_sender",
    "remove_other_reply_options": false,
    "privacy": "group_privacy_archives",
    "seperate_footers": false,
    "allow_downloads": "allow_downloads_by_members",
    "members_visible": "group_view_members_moderators",
    "subgroup_access": "sub_group_moderators",
    "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_limited",
    "chat_access": "group_access_limited",
    "handle_attachments": "group_attachments_bounced",
    "plain_text_only": false,
    "handle_virus": "handle_virus_block",
    "locked": false,
    "plan": "group_plan_basic",
    "trial_group": false,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 62,
    "org_id": 89,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 28,
    "max_number_of_reposts": 74,
    "email_delivery_default": "email_delivery_digest",
    "message_selection_default": "message_selection_all",
    "auto_follow_replies_default": false,
    "max_attachment_size_default": "max_attachment_size_large",
    "default_timezone": "",
    "default_time_pref": "military_time",
    "default_date_pref": "international_date",
    "default_monday_start": false,
    "disable_edits": false,
    "disable_no_email": false,
    "auto_close_threads": false,
    "close_threads_after": 11,
    "auto_moderate_threads": false,
    "moderate_threads_after": 45,
    "sticky_wiki_page_id": 37,
    "subgroupcategoryid": 6,
    "subs_count": 95,
    "pending_subs_count": 66,
    "pending_msgs_count": 28,
    "open_chats_count": 58,
    "threads_count": 47,
    "messages_count": 47,
    "org_domain": "",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "cover_photo_url": "",
    "icon_url": "",
    "group_url": "",
    "allow_parent_subs_to_post": false,
    "send_event_summaries": false,
    "event_summary_schedule": "event_summary_biweekly_friday",
    "send_invites_on_join": false,
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
    "email_address": "",
   },
 "sub_data": [
   {
    "id": 87,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 88,
    "group_id": 90,
    "group_name": "mygroup",
    "status": "sub_status_banned",
    "post_status": "sub_poststatus_allowed",
    "email_delivery": "email_delivery_digest",
    "message_selection": "message_selection_all",
    "auto_follow_replies": false,
    "max_attachment_size": "max_attachment_size_large",
    "approved_posts": 15,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_app_only",
    "pending_sub_notify": "sub_notify_app_only",
    "sub_notify": "sub_notify_app_only",
    "storage_notify": "sub_notify_app_only",
    "sub_group_notify": "sub_notify_app_only",
    "message_report_notify": "sub_notify_app_only",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "chat_notify": "sub_notify_app_only",
    "photo_notify": "sub_notify_app_only",
    "file_notify": "sub_notify_app_only",
    "wiki_notify": "sub_notify_app_only",
    "database_notify": "sub_notify_app_only",
    "email": "joe@example.com",
    "user_status": "user_status_bounced",
    "user_name": "joe",
    "timezone": "America/Los_Angeles",
    "full_name": "Joe Smith",
    "about_me": "",
    "location": "",
    "website": "https://example.com",
    "profile_photo_url": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "use_signature": false,
    "use_signature_email": false,
    "signature": "",
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "num_drafts": 41,
    "pending_subs": 8,
    "pending_msgs": 87,
    "cover_photo_url": "",
    "icon_url": "",
    "nice_group_name": "",
    "subs_count": 31,
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
   }
 ],
 "data": [
   {
    "id": 29,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 56,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 37,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 31,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 85,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hashtag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 26,
       "last_message_date": "2009-11-10T15:00:00-08:00",
       "muted": false,
       "followed": false,
      }
    ],
   }
 ],
}
View Topic List definition

Example Error Response

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

Get Topic

Get the messages within a specified topic. Messages are returned using the pagination request and object format.

Permissions Needed

You must have the archives_visible permission to use this call with a group.

Query Parameters
topic_id
required
number

ID of the topic to return.
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 .
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

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

Additional Errors
"bad_request"

"invalid topic_id" is returned if the topic id is missing or invalid.

GET /api/v1/gettopic

$ curl "https://groups.io/api/v1/gettopic?topic_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 13,
 "start_item": 90,
 "end_item": 94,
 "has_more": false,
 "next_page_token": 63,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "group_perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "group": 
   {
    "id": 33,
    "object": "group",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "title": "The Example Group",
    "name": "example",
    "nice_group_name": "",
    "alias": "",
    "desc": "This is the description for the example group.",
    "plain_desc": "This is the description for the example group.",
    "subject_tag": "[example]",
    "footer": "",
    "website": "",
    "announce": false,
    "moderation": "moderate_first_message",
    "new_users_moderated": false,
    "unmoderate_users_after": 47,
    "restricted": false,
    "allow_non_subs_to_post": false,
    "force_html_emails": false,
    "normalize_html_emails": false,
    "reply_to": "group_reply_only_to_sender",
    "remove_other_reply_options": false,
    "privacy": "group_privacy_archives",
    "seperate_footers": false,
    "allow_downloads": "allow_downloads_by_members",
    "members_visible": "group_view_members_moderators",
    "subgroup_access": "sub_group_moderators",
    "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_limited",
    "chat_access": "group_access_limited",
    "handle_attachments": "group_attachments_bounced",
    "plain_text_only": false,
    "handle_virus": "handle_virus_block",
    "locked": false,
    "plan": "group_plan_basic",
    "trial_group": false,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 78,
    "org_id": 24,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 59,
    "max_number_of_reposts": 53,
    "email_delivery_default": "email_delivery_digest",
    "message_selection_default": "message_selection_all",
    "auto_follow_replies_default": false,
    "max_attachment_size_default": "max_attachment_size_large",
    "default_timezone": "",
    "default_time_pref": "military_time",
    "default_date_pref": "international_date",
    "default_monday_start": false,
    "disable_edits": false,
    "disable_no_email": false,
    "auto_close_threads": false,
    "close_threads_after": 57,
    "auto_moderate_threads": false,
    "moderate_threads_after": 21,
    "sticky_wiki_page_id": 89,
    "subgroupcategoryid": 99,
    "subs_count": 0,
    "pending_subs_count": 5,
    "pending_msgs_count": 88,
    "open_chats_count": 38,
    "threads_count": 3,
    "messages_count": 55,
    "org_domain": "",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "cover_photo_url": "",
    "icon_url": "",
    "group_url": "",
    "allow_parent_subs_to_post": false,
    "send_event_summaries": false,
    "event_summary_schedule": "event_summary_biweekly_friday",
    "send_invites_on_join": false,
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
    "email_address": "",
   },
 "cover_photo_url": "",
 "sub_data": [
   {
    "id": 51,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 10,
    "group_id": 5,
    "group_name": "mygroup",
    "status": "sub_status_banned",
    "post_status": "sub_poststatus_allowed",
    "email_delivery": "email_delivery_digest",
    "message_selection": "message_selection_all",
    "auto_follow_replies": false,
    "max_attachment_size": "max_attachment_size_large",
    "approved_posts": 56,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_app_only",
    "pending_sub_notify": "sub_notify_app_only",
    "sub_notify": "sub_notify_app_only",
    "storage_notify": "sub_notify_app_only",
    "sub_group_notify": "sub_notify_app_only",
    "message_report_notify": "sub_notify_app_only",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "chat_notify": "sub_notify_app_only",
    "photo_notify": "sub_notify_app_only",
    "file_notify": "sub_notify_app_only",
    "wiki_notify": "sub_notify_app_only",
    "database_notify": "sub_notify_app_only",
    "email": "joe@example.com",
    "user_status": "user_status_bounced",
    "user_name": "joe",
    "timezone": "America/Los_Angeles",
    "full_name": "Joe Smith",
    "about_me": "",
    "location": "",
    "website": "https://example.com",
    "profile_photo_url": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "use_signature": false,
    "use_signature_email": false,
    "signature": "",
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "num_drafts": 66,
    "pending_subs": 28,
    "pending_msgs": 61,
    "cover_photo_url": "",
    "icon_url": "",
    "nice_group_name": "",
    "subs_count": 2,
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
   }
 ],
 "topic": 
   {
    "id": 83,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 46,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 63,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 76,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 2,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hashtag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 18,
       "last_message_date": "2009-11-10T15:00:00-08:00",
       "muted": false,
       "followed": false,
      }
    ],
   },
 "data": [
   {
    "id": 47,
    "object": "message",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 94,
    "group_id": 77,
    "topic_id": 63,
    "body": "",
    "quoted": "",
    "remainder": "",
    "snippet": "",
    "subject": "",
    "subject_with_tags": "",
    "name": "",
    "profile_photo_url": "",
    "is_plain_text": false,
    "msg_num": 96,
    "is_reply": false,
    "has_liked": false,
    "num_likes": 20,
    "is_closed": false,
    "is_moderated": false,
    "reply_to": "group_reply_only_to_sender",
    "can_repost": false,
    "hashtags": [
      {
       "id": 23,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 53,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hashtag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 37,
       "last_message_date": "2009-11-10T15:00:00-08:00",
       "muted": false,
       "followed": false,
      }
    ],
    "poll_id": 33,
    "attachments": [
      {
       "id": 41,
       "media_type": "",
       "download_url": "",
       "image_thumbnail_url": "",
       "filename": "",
      }
    ],
   }
 ],
}
View Message List definition

Example Error Response

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

Get Messages

Get the messages within a specified group. Messages are returned using the pagination request and object format.

Permissions Needed

You must have the archives_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name can be specified.
group_name
required
string

Name of the group. Either group_id or group_name can be specified.
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 .
extended
optional
number

If 1, then extended information is also returned with the call.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.

GET /api/v1/getmessages

$ curl "https://groups.io/api/v1/getmessages?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 59,
 "start_item": 33,
 "end_item": 43,
 "has_more": false,
 "next_page_token": 91,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "group_perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "group": 
   {
    "id": 2,
    "object": "group",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "title": "The Example Group",
    "name": "example",
    "nice_group_name": "",
    "alias": "",
    "desc": "This is the description for the example group.",
    "plain_desc": "This is the description for the example group.",
    "subject_tag": "[example]",
    "footer": "",
    "website": "",
    "announce": false,
    "moderation": "moderate_first_message",
    "new_users_moderated": false,
    "unmoderate_users_after": 78,
    "restricted": false,
    "allow_non_subs_to_post": false,
    "force_html_emails": false,
    "normalize_html_emails": false,
    "reply_to": "group_reply_only_to_sender",
    "remove_other_reply_options": false,
    "privacy": "group_privacy_archives",
    "seperate_footers": false,
    "allow_downloads": "allow_downloads_by_members",
    "members_visible": "group_view_members_moderators",
    "subgroup_access": "sub_group_moderators",
    "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_limited",
    "chat_access": "group_access_limited",
    "handle_attachments": "group_attachments_bounced",
    "plain_text_only": false,
    "handle_virus": "handle_virus_block",
    "locked": false,
    "plan": "group_plan_basic",
    "trial_group": false,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 36,
    "org_id": 46,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 7,
    "max_number_of_reposts": 40,
    "email_delivery_default": "email_delivery_digest",
    "message_selection_default": "message_selection_all",
    "auto_follow_replies_default": false,
    "max_attachment_size_default": "max_attachment_size_large",
    "default_timezone": "",
    "default_time_pref": "military_time",
    "default_date_pref": "international_date",
    "default_monday_start": false,
    "disable_edits": false,
    "disable_no_email": false,
    "auto_close_threads": false,
    "close_threads_after": 3,
    "auto_moderate_threads": false,
    "moderate_threads_after": 52,
    "sticky_wiki_page_id": 43,
    "subgroupcategoryid": 5,
    "subs_count": 98,
    "pending_subs_count": 25,
    "pending_msgs_count": 51,
    "open_chats_count": 15,
    "threads_count": 57,
    "messages_count": 87,
    "org_domain": "",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "cover_photo_url": "",
    "icon_url": "",
    "group_url": "",
    "allow_parent_subs_to_post": false,
    "send_event_summaries": false,
    "event_summary_schedule": "event_summary_biweekly_friday",
    "send_invites_on_join": false,
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
    "email_address": "",
   },
 "cover_photo_url": "",
 "sub_data": [
   {
    "id": 10,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 10,
    "group_id": 85,
    "group_name": "mygroup",
    "status": "sub_status_banned",
    "post_status": "sub_poststatus_allowed",
    "email_delivery": "email_delivery_digest",
    "message_selection": "message_selection_all",
    "auto_follow_replies": false,
    "max_attachment_size": "max_attachment_size_large",
    "approved_posts": 90,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_app_only",
    "pending_sub_notify": "sub_notify_app_only",
    "sub_notify": "sub_notify_app_only",
    "storage_notify": "sub_notify_app_only",
    "sub_group_notify": "sub_notify_app_only",
    "message_report_notify": "sub_notify_app_only",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "chat_notify": "sub_notify_app_only",
    "photo_notify": "sub_notify_app_only",
    "file_notify": "sub_notify_app_only",
    "wiki_notify": "sub_notify_app_only",
    "database_notify": "sub_notify_app_only",
    "email": "joe@example.com",
    "user_status": "user_status_bounced",
    "user_name": "joe",
    "timezone": "America/Los_Angeles",
    "full_name": "Joe Smith",
    "about_me": "",
    "location": "",
    "website": "https://example.com",
    "profile_photo_url": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "use_signature": false,
    "use_signature_email": false,
    "signature": "",
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "num_drafts": 32,
    "pending_subs": 98,
    "pending_msgs": 53,
    "cover_photo_url": "",
    "icon_url": "",
    "nice_group_name": "",
    "subs_count": 91,
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
   }
 ],
 "topic": 
   {
    "id": 82,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 84,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 97,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 67,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 37,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hashtag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 71,
       "last_message_date": "2009-11-10T15:00:00-08:00",
       "muted": false,
       "followed": false,
      }
    ],
   },
 "data": [
   {
    "id": 94,
    "object": "message",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 26,
    "group_id": 2,
    "topic_id": 81,
    "body": "",
    "quoted": "",
    "remainder": "",
    "snippet": "",
    "subject": "",
    "subject_with_tags": "",
    "name": "",
    "profile_photo_url": "",
    "is_plain_text": false,
    "msg_num": 79,
    "is_reply": false,
    "has_liked": false,
    "num_likes": 66,
    "is_closed": false,
    "is_moderated": false,
    "reply_to": "group_reply_only_to_sender",
    "can_repost": false,
    "hashtags": [
      {
       "id": 70,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 93,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hashtag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 86,
       "last_message_date": "2009-11-10T15:00:00-08:00",
       "muted": false,
       "followed": false,
      }
    ],
    "poll_id": 19,
    "attachments": [
      {
       "id": 81,
       "media_type": "",
       "download_url": "",
       "image_thumbnail_url": "",
       "filename": "",
      }
    ],
   }
 ],
}
View Message List definition

Example Error Response

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

Download Archives

Download Archives Download the archives of a group.

Permissions Needed

You must have the download_archives permission to use this call.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
start_msg_num
optional
number

Only returns messages with a message number greater than this number.
start_time
optional
date

Only returns messages more recently than this date. In format: 2020-01-25T15:30:15Z.
Returns

Returns an error if the parameters are invalid (e.g. specifying an invalid group id).

Additional Errors
"bad_request"

"invalid start_time format" is returned if the start_time parameter is not formatted correctly.
Notes
  • The archives will be returned as a .zip file, containing one file in mbox format.
  • This is a resource intensive call and may take some time to complete. This API call may be changed in the future to a webhook.
  • This call is rate limited to one call per person per group every 24 hours.

GET /api/v1/downloadarchives

$ curl "https://groups.io/api/v1/downloadarchives?group_id=2" \
-b "cookies.curl"

Example Error Response

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

Search Archives

Search the archives. The query string can include the following:

  • Limiting the search to specific hashtags can be done by include the hashtag names in the query, starting with #.
  • To exclude specific hashtags, include a dash before the hashtag, like: -#Tagname. Note, this is not currently implemented in the API.
  • Limiting the search to a specific person's messages can be done by including the text posterid:ID, where ID is the user_id of the person.
Permissions Needed

You must have the archives_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name can be specified.
group_name
required
string

Name of the group. Either group_id or group_name can be specified.
q
optional
string

The query string.
collapse_topics
optional
boolean

If the results should collapse topics.
exclude_sigs
optional
boolean

If signature matches should be excluded from the results.
start_date
optional
date

The start date of the search, in the user's timezone.
end_date
optional
date

The end date of the search, in the user's timezone.
preset_date_range
optional
string

Limit the search to a preset date range. Can be: past_hour, past_24_hours, past_week, past_month, past_year. This is only considered if neither start_date nor end_date are specified.
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.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

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

GET /api/v1/searcharchives

$ curl "https://groups.io/api/v1/searcharchives?group_id=12&q=find+this" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 52,
 "start_item": 75,
 "end_item": 85,
 "has_more": false,
 "next_page_token": 10,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "profile_photo_url": "",
 "name": "",
 "can_view_profile": false,
 "query": "",
 "collapse_topics": false,
 "exclude_sigs": false,
 "start_date": "2009-11-10T15:00:00-08:00",
 "end_date": "2009-11-10T15:00:00-08:00",
 "preset_date_range": "",
 "hashtag": 
   {
    "id": 87,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 49,
    "name": "",
    "alias": 
      {
      },
    "mods_only_post": false,
    "mods_only_replies": false,
    "no_email": false,
    "moderated": false,
    "special": false,
    "replies_unmoderated": false,
    "locked": false,
    "until": "hashtag_delete_day",
    "close_instead_of_delete": false,
    "description": "",
    "color_name": "tag_antique_pink",
    "color_hex": "",
    "reply_to": "thread_reply_group_default",
    "topic_count": 28,
    "last_message_date": "2009-11-10T15:00:00-08:00",
    "muted": false,
    "followed": false,
   },
 "poster_user_id": 18,
 "profile_photo_url": "",
 "name": "",
 "can_view_profile": false,
 "data": [
   {
    "id": 84,
    "object": "message_search_result",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 3,
    "topic_id": 24,
    "summary": "",
    "subject": "",
    "body": "",
    "user_id": 47,
    "profile_photo_url": "",
    "name": "",
    "can_view_profile": false,
    "rev_count": 12,
    "msg_num": 32,
    "num_msgs_in_topic": 16,
    "is_closed": false,
    "is_moderated": false,
    "is_sticky": false,
    "has_attachments": false,
    "hashtags": [
      {
       "id": 39,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 40,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hashtag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 86,
       "last_message_date": "2009-11-10T15:00:00-08:00",
       "muted": false,
       "followed": false,
      }
    ],
   }
 ],
}
View Message Search Results List definition

Example Error Response

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

Get Message History

Get the message history.

Permissions Needed

None.

Query Parameters
group_id
optional
number

ID of the group. If neither group_id nor group_name are specified, events from all subscriptions are returned.
group_name
optional
string

Name of the group. If neither group_id nor group_name are specified, events from all subscriptions are returned.
offset
optional
number

Timezone offset, in minutes.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a message history object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid group_id" is returned if the group id is missing or invalid.

GET /api/v1/getmessagehistory

$ curl "https://groups.io/api/v1/getmessagehistory?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "message_history",
 "month_counts": [
   {
    "object": "month_count",
    "year": 51,
    "month": 76,
    "msgs_sent": 40,
   }
 ],
 "tz_offset": 51,
}
View Message History definition

Example Error Response

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

Chats

There are several aspects to the Chat system.

  1. The Chat object represents a chat.
  2. Chats can be subscribed to.

New Chat

Create a new chat. The chat is created and the user is subscribed to the chat.

Permissions Needed

You must have the manage_chats permission to use this call with a group.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
subject
required
string

The subject of the chat.
desc
required
string

The description of the chat, in HTML format.
announce
required
bool

If true, send an announcement of the chat to the group.
csrf
required
string

The csrf_token from the user object returned when first logged in.
Returns

Returns a chat object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid group_id" is returned if the group id is missing or invalid.
"bad_request"

"invalid subject" is returned if the subject is missing or invalid.
"bad_request"

"invalid desc" is returned if the desc is missing or invalid.

POST /api/v1/newchat

$ curl "https://groups.io/api/v1/newchat" \
-b "cookies.curl" \
-d group_id=12&subject=Test&desc=testing&csrf=1234

Example Successful Response

 {
 "id": 44,
 "object": "chat",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 64,
 "profile_photo_url": "",
 "name": "",
 "can_view_profile": false,
 "group_id": 5,
 "subject": "The chat subject",
 "desc": "This is the description of the chat",
 "is_closed": false,
 "num_messages": 83,
 "chat_sub": 
   {
    "id": 1,
    "object": "chat_sub",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 90,
    "group_id": 2,
    "chat_id": 58,
    "last_msg_seen": 67,
   },
}
View Chat definition

Example Error Response

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

Update Chat

Update a chat object.

Permissions Needed

You must be the owner of the chat.

POST Parameters
chat_id
required
number

ID of the chat to update. You must be the owner of the chat.
csrf
required
string

The csrf_token from the user object returned when first logged in.
subject
optional
string

The subject of the chat.
desc
optional
string

The description of the chat, in HTML format.
is_closed
optional
boolean

If the chat is closed.
Returns

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

Additional Errors
"bad_request"

"invalid chat_id" is returned if the chat id is missing or invalid.

POST /api/v1/updatechat

$ curl "https://groups.io/api/v1/updatechat" \
-b "cookies.curl" \
-d chat_id=12&subject=Test&desc=testing&csrf=1234

Example Successful Response

 {
 "id": 31,
 "object": "chat",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 78,
 "profile_photo_url": "",
 "name": "",
 "can_view_profile": false,
 "group_id": 54,
 "subject": "The chat subject",
 "desc": "This is the description of the chat",
 "is_closed": false,
 "num_messages": 22,
 "chat_sub": 
   {
    "id": 23,
    "object": "chat_sub",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 42,
    "group_id": 8,
    "chat_id": 43,
    "last_msg_seen": 68,
   },
}
View Chat definition

Example Error Response

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

Get Chats

Get chats. Chats are returned using the pagination request and object format.

Permissions Needed

You must have the chat_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
show_closed
optional
boolean

If true, return closed chats. Otherwise return open chats.
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.
Returns

Returns a chat list object if successful. Returns an error if there is an error.

Additional Errors
No additional errors

GET /api/v1/getchats

$ curl "https://groups.io/api/v1/getchats?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 66,
 "start_item": 10,
 "end_item": 35,
 "has_more": false,
 "next_page_token": 40,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 4,
    "object": "chat",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 62,
    "profile_photo_url": "",
    "name": "",
    "can_view_profile": false,
    "group_id": 57,
    "subject": "The chat subject",
    "desc": "This is the description of the chat",
    "is_closed": false,
    "num_messages": 15,
    "chat_sub": 
      {
       "id": 71,
       "object": "chat_sub",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 39,
       "group_id": 30,
       "chat_id": 13,
       "last_msg_seen": 0,
      },
   }
 ],
}
View Chat List definition

Example Error Response

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

Delete Chat

Delete a chat object.

Permissions Needed

You must be the owner of the chat.

POST Parameters
chat_id
required
number

ID of the chat to delete. You must be the owner of the chat.
csrf
required
string

The csrf_token from the user object returned when first logged in.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid chat_id" is returned if the chat id is missing or invalid.

POST /api/v1/deletechat

$ curl "https://groups.io/api/v1/deletechat" \
-b "cookies.curl" \
-d chat_id=12&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Join Chat

Join a chat.

Permissions Needed

You must have the chat_visible permission to use this call with a group.

POST Parameters
chat_id
required
number

ID of the chat to join.
csrf
required
string

The csrf_token from the user object returned when first logged in.
Returns

Returns a chat sub object if successful. Returns an error if parameters are invalid (e.g. specifying an invalid chat_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid chat_id" is returned if the chat id is missing or invalid.
"bad_request"

"closed chat" is returned if the chat has been closed.
"bad_request"

"already subscribed" is returned if the user is already subscribed to the chat.

POST /api/v1/joinchat

$ curl "https://groups.io/api/v1/joinchat" \
-b "cookies.curl" \
-d chat_id=12&csrf=1234

Example Successful Response

 {
 "id": 59,
 "object": "chat_sub",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 20,
 "group_id": 83,
 "chat_id": 70,
 "last_msg_seen": 84,
}
View Chat Sub definition

Example Error Response

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

Chat Members

Get a list of the members of the chat.

Permissions Needed

You must be subscribed to the chat.

POST Parameters
chatsub_id
required
number

ID of the chatsub. You must be the owner of the chatsub.
Returns

Returns a member info list object if successful. 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"

"invalid chatsub_id" is returned if the chatsub id is missing or invalid.
"bad_request"

"closed chat" is returned if the chat has been closed.

POST /api/v1/chatmembers

$ curl "https://groups.io/api/v1/chatmembers" \
-b "cookies.curl" \
-d chatsub_id=12&csrf=1234

Example Successful Response

 {
 "object": "list",
 "total_count": 47,
 "start_item": 10,
 "end_item": 65,
 "has_more": false,
 "next_page_token": 62,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 29,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 20,
    "group_id": 48,
    "group_name": "mygroup",
    "status": "sub_status_banned",
    "post_status": "sub_poststatus_allowed",
    "email_delivery": "email_delivery_digest",
    "message_selection": "message_selection_all",
    "auto_follow_replies": false,
    "max_attachment_size": "max_attachment_size_large",
    "approved_posts": 56,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_app_only",
    "pending_sub_notify": "sub_notify_app_only",
    "sub_notify": "sub_notify_app_only",
    "storage_notify": "sub_notify_app_only",
    "sub_group_notify": "sub_notify_app_only",
    "message_report_notify": "sub_notify_app_only",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "chat_notify": "sub_notify_app_only",
    "photo_notify": "sub_notify_app_only",
    "file_notify": "sub_notify_app_only",
    "wiki_notify": "sub_notify_app_only",
    "database_notify": "sub_notify_app_only",
    "email": "joe@example.com",
    "user_status": "user_status_bounced",
    "user_name": "joe",
    "timezone": "America/Los_Angeles",
    "full_name": "Joe Smith",
    "about_me": "",
    "location": "",
    "website": "https://example.com",
    "profile_photo_url": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "use_signature": false,
    "use_signature_email": false,
    "signature": "",
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "num_drafts": 95,
    "pending_subs": 66,
    "pending_msgs": 0,
    "cover_photo_url": "",
    "icon_url": "",
    "nice_group_name": "",
    "subs_count": 56,
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
   }
 ],
}
View Member Info List definition

Example Error Response

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

Leave Chat

Leave a chat. Generally you do not want to use this. The normal way to leave a chat is to send a /leave message to an open chat.

Permissions Needed

You must be subscribed to the chat.

POST Parameters
chatsub_id
required
number

ID of the chatsub to delete. You must be the owner of the chatsub.
csrf
required
string

The csrf_token from the user object returned when first logged in.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid chatsub_id" is returned if the chatsub id is missing or invalid.

POST /api/v1/leavechat

$ curl "https://groups.io/api/v1/leavechat" \
-b "cookies.curl" \
-d chatsub_id=12&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Get Chat History

Get chat history. Chat messages are returned using the pagination request and object format.

Permissions Needed

You must be subscribed to the group.

GET Parameters
chat_id
required
number

ID of the chat to view.
Returns

Returns a chat message list object if successful. Returns an error if there is an error. Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid chat_id" is returned if the chat id is missing or invalid.

GET /api/v1/getchathistory

$ curl "https://groups.io/api/v1/getchathistory" \
-b "cookies.curl" \
-d chat_id=12

Example Successful Response

 {
 "object": "list",
 "total_count": 29,
 "start_item": 92,
 "end_item": 31,
 "has_more": false,
 "next_page_token": 77,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 86,
    "object": "chat_message",
    "created": "2009-11-10T15:00:00-08:00",
    "version": 20,
    "user_id": 99,
    "group_id": 62,
    "chat_id": 47,
    "type": "chat_msg_type_closed",
    "message": "",
    "msg_num": 92,
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
   }
 ],
}
View Chat Message List definition

Example Error Response

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

Chat Data

This is a websocket endpoint for sending and receiving chat messages. Once established, the client can post messages to the chat room using chat post objects. The client will receive a series of chat message objects representing posts from other members of the chat room. If no_history is not specified, upon establishment of the connnection, the most recent 50 chat_message objects are returned.

Permissions Needed

You must be subscribed to the chat.

POST Parameters
chatsub_id
required
number

ID of the chatsub to enter. You must be the owner of the chatsub.
csrf
required
string

The csrf_token from the user object returned when first logged in.
no_history
optional
boolean

If true, do not automatically send back recent chat history.
Returns

Returns a series of a chat message objects if successful. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid chatsub_id" is returned if the chatsub id is missing or invalid.
"bad_request"

"closed chat" is returned if the chat is closed.

WSS /api/v1/chatdata

$ curl -i -N \
--no-buffer \
-H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Host: api.groups.io" \
-H "Origin: https://api.groups.io" \
-H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
-H "Sec-WebSocket-Version: 13" \
-b "cookies.curl" \
https://groups.io/api/v1/chatdata?chatsub_id=12&csrf=1234

Example Error Response

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

Databases

Get Databases

Get databases. Databases are returned using the pagination request and object format.

Permissions Needed

You must have the database_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
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.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a database list object if successful. Returns an error if there is an error.

Additional Errors
No additional errors

GET /api/v1/getdatabases

$ curl "https://groups.io/api/v1/getdatabases?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 88,
 "start_item": 11,
 "end_item": 3,
 "has_more": false,
 "next_page_token": 88,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 18,
    "object": "databasetable",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 56,
    "user_id": 19,
    "name": "",
    "short_desc": "",
    "desc": "",
    "desc_type": "",
    "edit_table": "database_access_all",
    "edit_rows": "database_access_all",
    "add_rows": "database_access_all",
    "view_table": "database_access_all",
    "num_rows": 7,
    "max_row_id": 57,
    "num_columns": 52,
    "max_col_id": 75,
    "display_template": "",
    "columns": [
      {
       "id": 81,
       "name": "",
       "type": "address",
       "required": false,
       "color": "column_color_antique_pink",
       "choices": [""],
       "width": 53,
       "default_hidden": false,
       "description": "",
       "default_country": "",
      }
    ],
    "id_default_hidden": false,
    "updated_default_hidden": false,
   }
 ],
}
View Database Table List definition

Example Error Response

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

Get Database Rows

Get database rows. Database rows are returned using the pagination request and object format.

Permissions Needed

You must have the database_visible permission to use this call with a group.

Query Parameters
database_id
required
number

ID of the database.
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.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a database row list object if successful. Returns an error if there is an error.

Additional Errors
No additional errors

GET /api/v1/getdatabaserows

$ curl "https://groups.io/api/v1/getdatabaserows?database_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 95,
 "start_item": 17,
 "end_item": 93,
 "has_more": false,
 "next_page_token": 70,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 96,
    "object": "databaserow",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 86,
    "table_id": 32,
    "row_num": 20,
    "vals": [
      {
       "col_id": 60,
       "col_type": "address",
       "text": "",
       "html_text": "",
       "date": "2009-11-10T15:00:00-08:00",
       "time": "2009-11-10T15:00:00-08:00",
       "checked": false,
       "multi_choice": [22],
       "street_address1": "",
       "street_address2": "",
       "city": "",
       "state": "",
       "zip": "",
       "country": "",
       "title": "",
       "url": "",
       "desc": "",
       "image_name": "",
       "lat": "",
       "lng": "",
      }
    ],
    "num_vals": 29,
   }
 ],
}
View Database Row List definition

Example Error Response

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

Delivery

Get Delivery Info

Get a user's group specific delivery information.

Permissions Needed

None if viewing your own delivery information. If viewing another member's delivery information, you need the manage_members permission.

Query Parameters
group_id
optional
number

ID of the group. If neither group_id nor group_name are specified, events from all subscriptions are returned.
group_name
optional
string

Name of the group. If neither group_id nor group_name are specified, events from all subscriptions are returned.
member_info_id
optional
number

If specified, return the delivery information for this member. You must have the manage_members permission to specify this.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a delivery info object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid group_id" is returned if the group id is missing or invalid.

GET /api/v1/getdeliveryinfo

$ curl "https://groups.io/api/v1/getdeliveryinfo?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "delivery_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "group_id": 61,
 "success_msg_id": 60,
 "success_time": "2009-11-10T15:00:00-08:00",
 "success_subject": "",
 "success_type": "delivery_bounce_probe",
 "success_response": "",
 "attempt_msg_id": 20,
 "attempt_time": "2009-11-10T15:00:00-08:00",
 "attempt_subject": "",
 "attempt_type": "delivery_bounce_probe",
 "attempt_response": "",
 "bounces": [
   {
    "object": "bounce_info",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 79,
    "msg_id": 54,
    "subject": "",
    "response": "",
    "is_hard": false,
    "type": "delivery_bounce_probe",
   }
 ],
}
View Delivery Info definition

Example Error Response

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

Get Bounce Info

Get a user's bounce information.

Permissions Needed

None.

Query Parameters
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.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a bounce info list object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors

None.

GET /api/v1/getbounceinfo

$ curl "https://groups.io/api/v1/getbounceinfo" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 64,
 "start_item": 60,
 "end_item": 51,
 "has_more": false,
 "next_page_token": 81,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "object": "bounce_info",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 57,
    "msg_id": 16,
    "subject": "",
    "response": "",
    "is_hard": false,
    "type": "delivery_bounce_probe",
   }
 ],
}
View Bounce Info List definition

Example Error Response

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

Drafts

A draft represent a post as it is being written. The sequence to post a message to a group is as follows:

  1. Create a new draft with /newdraft.
  2. Compose the message, periodically saving it with /updatedraft.
  3. Optionally add attachments, using /addattachments.
  4. Once complete, sending the draft as a message with /postdraft.

There are also several draft maintenance endpoints.

New Draft

Create a new draft object.

Permissions Needed

You must have the can_post permission to use this call with a group.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
draft_type
required
string

Type of draft. Currently, draft_type_post, draft_type_reply, draft_type_post_to_sub and draft_type_dm are the only allowed types.
csrf
required
string

The csrf_token from the user object returned when first logged in.
message_id
may be required
number

If this is a 'draft_type_reply', you must specify the ID of the message you are replying to.
dm_member_id
may be required
number

If this is a draft_type_dm, you must specify the ID of the member you are sending a message to.
member_id
may be required
number

If this is a draft_type_post_to_sub, you must specify the ID of the member you are sending a message to. You can specify more than one member_ids.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

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

Additional Errors
"bad_request"

"invalid group_id" is returned if the group id is missing or invalid.
"bad_request"

"invalid draft_type" is returned if the draft type is missing or invalid.
"bad_request"

"missing dm_member_id" is returned if the draft type is draft_type_dm and dm_member_id is missing.

POST /api/v1/newdraft

$ curl "https://groups.io/api/v1/newdraft" \
-b "cookies.curl" \
-d group_id=12&csrf=12345

Example Successful Response

 {
 "id": 0,
 "object": "draft",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 39,
 "group_id": 37,
 "draft_type": "",
 "subject": "",
 "body": "",
 "body_type": "",
 "is_special": false,
 "num_attachments": 33,
 "next_attachment_id": 61,
 "message_id": 4,
 "bcc_me": false,
 "bcc_all": false,
}
View Draft definition

Example Error Response

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

Update Draft

Update a draft object.

Permissions Needed

You must be the owner of the draft.

POST Parameters
draft_id
required
number

ID of the draft to update. You must be the owner of the draft.
csrf
required
string

The csrf_token from the user object returned when first logged in.
subject
optional
string

Subject of the draft.
body
optional
string

Body of the draft, in HTML.
is_special
optional
boolean

If this post should be sent as a special message (only applies to moderators/owners).
bcc_me
optional
boolean

If the sender should be BCC'ed when this draft is posted (only applies to draft_type_reply)
bcc_all
optional
boolean

If all moderators should be BCC'ed when this draft is posted (only applies to draft_type_post_to_sub).
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

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

Additional Errors
"bad_request"

"invalid draft_id" is returned if the draft id is missing or invalid.

POST /api/v1/updatedraft

$ curl "https://groups.io/api/v1/updatedraft" \
-b "cookies.curl" \
-d draft_id=12&csrf=12345

Example Successful Response

 {
 "id": 85,
 "object": "draft",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 9,
 "group_id": 15,
 "draft_type": "",
 "subject": "",
 "body": "",
 "body_type": "",
 "is_special": false,
 "num_attachments": 19,
 "next_attachment_id": 14,
 "message_id": 40,
 "bcc_me": false,
 "bcc_all": false,
}
View Draft definition

Example Error Response

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

Get Drafts

Get drafts. Drafts are returned using the pagination request and object format.

Permissions Needed

None

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
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 created or subject.
sort_dir
optional
string

Sort direction. Can be asc or desc.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a draft list object if successful. Returns an error if there is an error.

Additional Errors
No additional errors

GET /api/v1/getdrafts

$ curl "https://groups.io/api/v1/getdrafts" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 62,
 "start_item": 40,
 "end_item": 0,
 "has_more": false,
 "next_page_token": 84,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 73,
    "object": "draft",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 35,
    "group_id": 43,
    "draft_type": "",
    "subject": "",
    "body": "",
    "body_type": "",
    "is_special": false,
    "num_attachments": 21,
    "next_attachment_id": 90,
    "message_id": 74,
    "bcc_me": false,
    "bcc_all": false,
   }
 ],
}
View Draft List definition

Example Error Response

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

Delete Draft

Delete a draft object.

Permissions Needed

You must be the owner of the draft.

POST Parameters
draft_id
required
number

ID of the draft to delete. You must be the owner of the draft.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Additional Errors
"bad_request"

"invalid draft_id" is returned if the draft id is missing or invalid.

POST /api/v1/deletedraft

$ curl "https://groups.io/api/v1/deletedraft" \
-b "cookies.curl" \
-d draft_id=12&csrf=12345

Successful Response

HTTP 200

Example Error Response

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

Upload Attachments

Upload attachments as part of a draft.

Permissions Needed

You must be the owner of the draft.

POST Parameters
draft_id
required
number

ID of the draft to associate the attachment to. You must be the owner of the draft.
fileupload
required
multipart file

Multipart file upload of one or more attachments.
csrf
required
string

The csrf_token from the user object returned when first logged in.
inline
optional
boolean

If the attachments are inline images.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a draft attachment list object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid draft_id" is returned if the draft id is missing or invalid.

POST /api/v1/uploadattachments

$ curl "https://groups.io/api/v1/uploadattachments" \
-b "cookies.curl"
-F fileupload=@path_to_file \
-F "draft_id=12" \
-F "csrf=12345"

Example Successful Response

 {
 "object": "list",
 "total_count": 69,
 "start_item": 70,
 "end_item": 36,
 "has_more": false,
 "next_page_token": 38,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 72,
    "object": "draft_attachment",
    "draft_id": 44,
    "url": "",
    "filename": "",
    "size": 95,
    "content_type": "",
    "inline": false,
   }
 ],
}
View Draft Attachment List definition

Example Error Response

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

Get Attachments

Get attachments.

Permissions Needed

You must be the owner of the draft.

POST Parameters
draft_id
required
number

ID of the draft containing the attachments. You must be the owner of the draft.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a draft attachment list object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid draft_id" is returned if the draft id is missing or invalid.

GET /api/v1/getattachments

$ curl "https://groups.io/api/v1/getattachments?draft_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 74,
 "start_item": 37,
 "end_item": 24,
 "has_more": false,
 "next_page_token": 93,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 6,
    "object": "draft_attachment",
    "draft_id": 48,
    "url": "",
    "filename": "",
    "size": 52,
    "content_type": "",
    "inline": false,
   }
 ],
}
View Draft Attachment List definition

Example Error Response

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

Delete Attachment

Delete an attachment.

Permissions Needed

You must be the owner of the draft and attachment.

POST Parameters
draft_id
required
number

ID of the draft containing the attachment to delete. You must be the owner of the draft.
attachment_id
required
number

Attachment ID to delete.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Additional Errors
"bad_request"

"invalid draft_id" is returned if the draft id is missing or invalid.
"bad_request"

"invalid attachment_id" is returned if the attachment ID is missing or invalid.

POST /api/v1/deleteattachment

$ curl "https://groups.io/api/v1/deleteattachment" \
-b "cookies.curl" \
-d draft_id=12&csrf=12345

Successful Response

HTTP 200

Example Error Response

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

Post Draft

Post Draft.

Permissions Needed

You must be the owner of the draft. You must have the can_post permission in the group.

POST Parameters
draft_id
required
number

ID of the draft to post. You must be the owner of the draft.
csrf
required
string

The csrf_token from the user object returned when first logged in.
reply
optional
string

Only applicable if this draft is a reply to a message. Possible values are: sender, group_and_sender, mods.
from_owner
optional
boolean

Only applicable if this draft is a new post and the poster is a moderator or owner of the group. If true, send the post from the groupname+owner email address.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a success object on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Success Responses
"pending post"

Returned if the post requires approval before it is sent to the group.
Additional Errors
"bad_request"

"invalid draft_id" is returned if the draft id is missing or invalid.
"bad_request"

"no subject" is returned if the draft is missing a subject.
"bad_request"

"no body" is returned if the draft is missing a body.
"bad_request"

"need hashtag" is returned if the subject needs a hashtag.
"bad_request"

"restricted hashtag" is returned if the subject contains a hashtag that the user does not have permission to use.
"bad_request"

"mod only hashtag" is returned if the subject contains a hashtag that only moderators/owners can use.
"bad_request"

"private message" is returned if the subject starts with "Private:".
"bad_request"

"post too big" is returned if the body is too large to send.
"bad_request"

"announcement group" is returned if the group is an announcement group and the sender is not a moderator/owner.
"bad_request"

"group out of space" is returned if the group is out of space.
"bad_request"

"bad attachment" is returned if the message contains an attachment that isn't allowed.
"bad_request"

"not subscribed" is returned if the user is not subscribed to the group.
"bad_request"

"invalid reply" is returned if the reply parameter is invalid.

POST /api/v1/postdraft

$ curl "https://groups.io/api/v1/postdraft" \
-b "cookies.curl" \
-d draft_id=12&csrf=12345

Successful Response

HTTP 200

Example Error Response

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

Events

With RSVPs, here is the flow:

  • When viewing an event, if the rsvp field of the Event object is true, an RSVP is requested.
  • If the comment_label field in the Event is not empty, display a text field for entry of a comment.
  • If the additional_guests field of the Event object is true, display a drop down to select the number of additional guests.
  • If the has_rsvp field of the Event object is false, display three buttons: Will Attend, Will Not Attend, Not Sure.
  • If the has_rsvp field of the Event object is true, the rsvp_type, rsvp_comment and rsvp_additional_guests fields represent the previous RSVP response.
  • If the rsvp_type is rsvp_waitlist, that means the person is waitlisted. In this case, the Will Attend button should be 'Update Waitlisted'. This button should return a response value of rsvp_yes, not rsvp_waitlist.
  • On successfully calling the /v1/rsvp endpoint, an rsvp object is returned. If the type field is set to rsvp_waitlist, that means the user has been waitlisted, and a message should be shown to them announcing that.

Get Event

Get a single event.

Permissions Needed

You must be subscribed to the group associated with the event.

Query Parameters
event_id
required
number

The ID of the event to return.
Returns

Returns the event object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call. extended - optional, boolean: If true, the endpoint will return additional information. See Extended Return Information for more information.

Additional Errors
"bad_request"

"invalid event_id" is returned if the event id is missing or invalid.
"bad_request"

"not subscribed to group" is returned if the event belongs to a group the user is not a member of.

GET /api/v1/getevent

$ curl "https://groups.io/api/v1/getevent?event_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "id": 20,
 "object": "event",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "creator_name": "@JohnSmith",
 "group_id": 22,
 "group_name": "",
 "nice_group_name": "",
 "start_time": "2009-11-10T15:00:00-08:00",
 "end_time": "2009-11-10T15:00:00-08:00",
 "timezone": "",
 "all_day": false,
 "name": "",
 "location": "",
 "description": "",
 "organizer_name": "",
 "organizer_email": "",
 "organizer_phone": "",
 "color_name": "tag_antique_pink",
 "color_hex": "",
 "rsvp": false,
 "max_attendees": 71,
 "additional_guests": false,
 "comment_label": "",
 "yes_message": "",
 "has_rsvp": false,
 "rsvp_type": "",
 "rsvp_comment": "",
 "rsvp_additional_guests": 17,
}
View Event definition

Example Error Response

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

Get Events

Get a set of events. If group_id or group_name are specified, only events from those groups are returned. If neither are specified, events from all the groups subscribed to by the logged in user are returned. Event objects are returned using the pagination request and object format.

Query Parameters
start
required
string

The earliest date to return events from. In the form YYYY-MM-DD.
end
optional
string

The latest date to return events from. In the form YYYY-MM-DD.
group_id
optional
number

ID of the group. If neither group_id nor group_name are specified, events from all subscriptions are returned.
group_name
optional
string

Name of the group. If neither group_id nor group_name are specified, events from all subscriptions are returned.
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. You must also continue to specify the same start and end parameters.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.

GET /api/v1/getevents

$ curl "https://groups.io/api/v1/getevents?start=2019-06-19&limit=2" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 51,
 "start_item": 65,
 "end_item": 82,
 "has_more": false,
 "next_page_token": 79,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 92,
    "object": "event",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "creator_name": "@JohnSmith",
    "group_id": 29,
    "group_name": "",
    "nice_group_name": "",
    "start_time": "2009-11-10T15:00:00-08:00",
    "end_time": "2009-11-10T15:00:00-08:00",
    "timezone": "",
    "all_day": false,
    "name": "",
    "location": "",
    "description": "",
    "organizer_name": "",
    "organizer_email": "",
    "organizer_phone": "",
    "color_name": "tag_antique_pink",
    "color_hex": "",
    "rsvp": false,
    "max_attendees": 31,
    "additional_guests": false,
    "comment_label": "",
    "yes_message": "",
    "has_rsvp": false,
    "rsvp_type": "",
    "rsvp_comment": "",
    "rsvp_additional_guests": 21,
   }
 ],
}
View Event List definition

Example Error Response

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

RSVP To An Event

RSVP to an event.

Permissions Needed

You must be subscribed to the group.

POST Parameters
event_id
required
number

ID of the event to RSVP to. You must be subscribed to the group.
response
required
string

Can be one of: rsvp_maybe, rsvp_no, rsvp_yes.
additional_guests
required
number
comment
required
string
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

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

Additional Errors
"bad_request"

"invalid event_id" is returned if the event id is missing or invalid.
"bad_request"

"locked event" is returned if the event has been locked.
"bad_request"

"not subscribed" is returned if the user is not subscribed to the group.
"bad_request"

"waitlist response" is returned if the response field is rsvp_waitlist.
Notes
  • rsvp_waitlist is not a valid value for response. The user should only be given the options of Yes, No, or Maybe.
  • If the response is rsvp_yes, check the type field of the returned RSVP object. If it is rsvp_waitlist, the person has been waitlisted.

POST /api/v1/rsvp

$ curl "https://groups.io/api/v1/rsvp" \
-b "cookies.curl" \
-d event_id=12&response=rsvp_yes&csrf=12345

Example Successful Response

 {
 "id": 55,
 "object": "rsvp",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "event_id": 11,
 "group_id": 43,
 "user_id": 53,
 "user_name": "",
 "full_name": "",
 "email": "",
 "profile_photo_url": "",
 "type": "rsvp_maybe",
 "comment": "",
 "additional_guests": 66,
}
View RSVP definition

Example Error Response

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

Feed

Get Feed

Get the list of feeds associated with the logged in user. Feed objects are returned using the pagination request and object format.

Query Parameters
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.

GET /api/v1/getfeed

$ curl "https://groups.io/api/v1/getfeed?limit=2&page_token=1" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 59,
 "start_item": 67,
 "end_item": 8,
 "has_more": false,
 "next_page_token": 8,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "object": "feed",
    "member_info": 
      {
       "id": 28,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 53,
       "group_id": 74,
       "group_name": "mygroup",
       "status": "sub_status_banned",
       "post_status": "sub_poststatus_allowed",
       "email_delivery": "email_delivery_digest",
       "message_selection": "message_selection_all",
       "auto_follow_replies": false,
       "max_attachment_size": "max_attachment_size_large",
       "approved_posts": 84,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_app_only",
       "pending_sub_notify": "sub_notify_app_only",
       "sub_notify": "sub_notify_app_only",
       "storage_notify": "sub_notify_app_only",
       "sub_group_notify": "sub_notify_app_only",
       "message_report_notify": "sub_notify_app_only",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "chat_notify": "sub_notify_app_only",
       "photo_notify": "sub_notify_app_only",
       "file_notify": "sub_notify_app_only",
       "wiki_notify": "sub_notify_app_only",
       "database_notify": "sub_notify_app_only",
       "email": "joe@example.com",
       "user_status": "user_status_bounced",
       "user_name": "joe",
       "timezone": "America/Los_Angeles",
       "full_name": "Joe Smith",
       "about_me": "",
       "location": "",
       "website": "https://example.com",
       "profile_photo_url": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "use_signature": false,
       "use_signature_email": false,
       "signature": "",
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "num_drafts": 75,
       "pending_subs": 74,
       "pending_msgs": 6,
       "cover_photo_url": "",
       "icon_url": "",
       "nice_group_name": "",
       "subs_count": 37,
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "perms": 
         {
          "object": "perms",
          "archives_visible": false,
          "polls_visible": false,
          "members_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
          "hashtags_visible": false,
          "guidelines_visible": false,
          "subgroups_visible": false,
          "open_donations_visible": false,
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": false,
          "create_hashtags": false,
          "manage_hashtags": false,
          "manage_integrations": false,
          "manage_group_settings": false,
          "make_moderator": false,
          "manage_member_subscription_options": false,
          "manage_pending_members": false,
          "remove_members": false,
          "ban_members": false,
          "manage_group_billing": false,
          "manage_group_payments": false,
          "edit_archives": false,
          "manage_pending_messages": false,
          "invite_members": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "manage_photos": false,
          "manage_members": false,
          "manage_calendar": false,
          "manage_chats": false,
          "view_member_directory": false,
          "manage_files": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
         },
      },
    "group": 
      {
       "id": 86,
       "object": "group",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "title": "The Example Group",
       "name": "example",
       "nice_group_name": "",
       "alias": "",
       "desc": "This is the description for the example group.",
       "plain_desc": "This is the description for the example group.",
       "subject_tag": "[example]",
       "footer": "",
       "website": "",
       "announce": false,
       "moderation": "moderate_first_message",
       "new_users_moderated": false,
       "unmoderate_users_after": 67,
       "restricted": false,
       "allow_non_subs_to_post": false,
       "force_html_emails": false,
       "normalize_html_emails": false,
       "reply_to": "group_reply_only_to_sender",
       "remove_other_reply_options": false,
       "privacy": "group_privacy_archives",
       "seperate_footers": false,
       "allow_downloads": "allow_downloads_by_members",
       "members_visible": "group_view_members_moderators",
       "subgroup_access": "sub_group_moderators",
       "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_limited",
       "chat_access": "group_access_limited",
       "handle_attachments": "group_attachments_bounced",
       "plain_text_only": false,
       "handle_virus": "handle_virus_block",
       "locked": false,
       "plan": "group_plan_basic",
       "trial_group": false,
       "has_cover_photo": false,
       "has_icon": false,
       "parent_group_id": 14,
       "org_id": 58,
       "max_photo_size_email": "max_photo_size_ex_small",
       "max_photo_size_photos": "max_photo_size_ex_small",
       "max_photo_size_databases": "max_photo_size_ex_small",
       "max_photo_size_wiki_images": "max_photo_size_ex_small",
       "hash_tags_required": false,
       "hash_tag_permissions": "hash_tag_create_mods_bounce",
       "bounce_attachments": false,
       "allow_photos_in_files": false,
       "allow_reposts": false,
       "min_days_between_reposts": 59,
       "max_number_of_reposts": 46,
       "email_delivery_default": "email_delivery_digest",
       "message_selection_default": "message_selection_all",
       "auto_follow_replies_default": false,
       "max_attachment_size_default": "max_attachment_size_large",
       "default_timezone": "",
       "default_time_pref": "military_time",
       "default_date_pref": "international_date",
       "default_monday_start": false,
       "disable_edits": false,
       "disable_no_email": false,
       "auto_close_threads": false,
       "close_threads_after": 23,
       "auto_moderate_threads": false,
       "moderate_threads_after": 24,
       "sticky_wiki_page_id": 87,
       "subgroupcategoryid": 57,
       "subs_count": 74,
       "pending_subs_count": 39,
       "pending_msgs_count": 31,
       "open_chats_count": 46,
       "threads_count": 83,
       "messages_count": 28,
       "org_domain": "",
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "cover_photo_url": "",
       "icon_url": "",
       "group_url": "",
       "allow_parent_subs_to_post": false,
       "send_event_summaries": false,
       "event_summary_schedule": "event_summary_biweekly_friday",
       "send_invites_on_join": false,
       "perms": 
         {
          "object": "perms",
          "archives_visible": false,
          "polls_visible": false,
          "members_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
          "hashtags_visible": false,
          "guidelines_visible": false,
          "subgroups_visible": false,
          "open_donations_visible": false,
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": false,
          "create_hashtags": false,
          "manage_hashtags": false,
          "manage_integrations": false,
          "manage_group_settings": false,
          "make_moderator": false,
          "manage_member_subscription_options": false,
          "manage_pending_members": false,
          "remove_members": false,
          "ban_members": false,
          "manage_group_billing": false,
          "manage_group_payments": false,
          "edit_archives": false,
          "manage_pending_messages": false,
          "invite_members": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "manage_photos": false,
          "manage_members": false,
          "manage_calendar": false,
          "manage_chats": false,
          "view_member_directory": false,
          "manage_files": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
         },
       "email_address": "",
      },
    "topics": [
      {
       "topic": 
         {
          "id": 16,
          "object": "topic",
          "created": "2009-11-10T15:00:00-08:00",
          "updated": "2009-11-10T15:00:00-08:00",
          "group_id": 26,
          "group_subject_tag": "",
          "subject": "",
          "summary": "",
          "name": "",
          "profile_photo_url": "",
          "num_messages": 77,
          "is_sticky": false,
          "is_moderated": false,
          "is_closed": false,
          "has_attachments": false,
          "reply_to": "thread_reply_group_default",
          "most_recent_message": "2009-11-10T15:00:00-08:00",
          "hashtags": [
            {
             "id": 12,
             "object": "hashtag",
             "created": "2009-11-10T15:00:00-08:00",
             "group_id": 36,
             "name": "",
             "alias": 
               {
               },
             "mods_only_post": false,
             "mods_only_replies": false,
             "no_email": false,
             "moderated": false,
             "special": false,
             "replies_unmoderated": false,
             "locked": false,
             "until": "hashtag_delete_day",
             "close_instead_of_delete": false,
             "description": "",
             "color_name": "tag_antique_pink",
             "color_hex": "",
             "reply_to": "thread_reply_group_default",
             "topic_count": 51,
             "last_message_date": "2009-11-10T15:00:00-08:00",
             "muted": false,
             "followed": false,
            }
          ],
         },
       "images": [
         {
          "id": "",
          "object": "attachment",
          "created": "2009-11-10T15:00:00-08:00",
          "group_id": 5,
          "user_id": 62,
          "thread_id": 89,
          "message_num": 98,
          "attach_num": 87,
          "type": "",
          "sub_type": "",
          "name": "",
          "content": "",
          "image_width": 30,
          "image_height": 9,
          "thumbnail_url": "",
         }
       ],
      }
    ],
    "events": [
      {
       "id": 28,
       "object": "event",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "creator_name": "@JohnSmith",
       "group_id": 59,
       "group_name": "",
       "nice_group_name": "",
       "start_time": "2009-11-10T15:00:00-08:00",
       "end_time": "2009-11-10T15:00:00-08:00",
       "timezone": "",
       "all_day": false,
       "name": "",
       "location": "",
       "description": "",
       "organizer_name": "",
       "organizer_email": "",
       "organizer_phone": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "rsvp": false,
       "max_attendees": 61,
       "additional_guests": false,
       "comment_label": "",
       "yes_message": "",
       "has_rsvp": false,
       "rsvp_type": "",
       "rsvp_comment": "",
       "rsvp_additional_guests": 2,
      }
    ],
    "files": [
      {
       "id": 18,
       "object": "file",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 45,
       "group_id": 71,
       "name": "",
       "desc": "",
       "size": 53,
       "path": "",
       "parent_folder_id": 40,
       "is_folder": false,
       "type": "",
       "count": 20,
       "media_type": "",
       "download_url": "",
       "display_name": "",
       "user_name": "",
       "profile_photo_url": "",
       "profile_privacy": "",
       "email": "",
      }
    ],
    "photos": [
      {
       "id": 81,
       "object": "photo",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 5,
       "group_id": 76,
       "name": "",
       "desc": "",
       "media_type": "image/jpeg",
       "size": 9,
       "attachment_num": 66,
       "width": 56,
       "height": 95,
       "album_id": 80,
       "display_name": "",
       "user_name": "",
       "profile_photo_url": "",
       "profile_privacy": "",
       "email": "",
       "format": "gif",
       "focal_length": 3.2,
       "iso": 34,
       "aperture": 3.2,
       "shutter_speed": 77,
       "taken": 67,
       "make": "",
       "model": "",
       "thumbnail_url": "",
       "download_url": "",
      }
    ],
    "chats": [
      {
       "id": 78,
       "object": "chat",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 75,
       "profile_photo_url": "",
       "name": "",
       "can_view_profile": false,
       "group_id": 93,
       "subject": "The chat subject",
       "desc": "This is the description of the chat",
       "is_closed": false,
       "num_messages": 80,
       "chat_sub": 
         {
          "id": 8,
          "object": "chat_sub",
          "created": "2009-11-10T15:00:00-08:00",
          "updated": "2009-11-10T15:00:00-08:00",
          "user_id": 31,
          "group_id": 65,
          "chat_id": 58,
          "last_msg_seen": 84,
         },
      }
    ],
    "wikis": [
      {
       "id": 42,
       "object": "wiki_page",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 23,
       "group_id": 62,
       "title": "",
       "path": "",
       "locked": false,
       "rev_count": 73,
      }
    ],
    "subgroups": [
      {
       "id": 72,
       "object": "group",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "title": "The Example Group",
       "name": "example",
       "nice_group_name": "",
       "alias": "",
       "desc": "This is the description for the example group.",
       "plain_desc": "This is the description for the example group.",
       "subject_tag": "[example]",
       "footer": "",
       "website": "",
       "announce": false,
       "moderation": "moderate_first_message",
       "new_users_moderated": false,
       "unmoderate_users_after": 53,
       "restricted": false,
       "allow_non_subs_to_post": false,
       "force_html_emails": false,
       "normalize_html_emails": false,
       "reply_to": "group_reply_only_to_sender",
       "remove_other_reply_options": false,
       "privacy": "group_privacy_archives",
       "seperate_footers": false,
       "allow_downloads": "allow_downloads_by_members",
       "members_visible": "group_view_members_moderators",
       "subgroup_access": "sub_group_moderators",
       "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_limited",
       "chat_access": "group_access_limited",
       "handle_attachments": "group_attachments_bounced",
       "plain_text_only": false,
       "handle_virus": "handle_virus_block",
       "locked": false,
       "plan": "group_plan_basic",
       "trial_group": false,
       "has_cover_photo": false,
       "has_icon": false,
       "parent_group_id": 58,
       "org_id": 27,
       "max_photo_size_email": "max_photo_size_ex_small",
       "max_photo_size_photos": "max_photo_size_ex_small",
       "max_photo_size_databases": "max_photo_size_ex_small",
       "max_photo_size_wiki_images": "max_photo_size_ex_small",
       "hash_tags_required": false,
       "hash_tag_permissions": "hash_tag_create_mods_bounce",
       "bounce_attachments": false,
       "allow_photos_in_files": false,
       "allow_reposts": false,
       "min_days_between_reposts": 96,
       "max_number_of_reposts": 48,
       "email_delivery_default": "email_delivery_digest",
       "message_selection_default": "message_selection_all",
       "auto_follow_replies_default": false,
       "max_attachment_size_default": "max_attachment_size_large",
       "default_timezone": "",
       "default_time_pref": "military_time",
       "default_date_pref": "international_date",
       "default_monday_start": false,
       "disable_edits": false,
       "disable_no_email": false,
       "auto_close_threads": false,
       "close_threads_after": 13,
       "auto_moderate_threads": false,
       "moderate_threads_after": 31,
       "sticky_wiki_page_id": 74,
       "subgroupcategoryid": 6,
       "subs_count": 40,
       "pending_subs_count": 31,
       "pending_msgs_count": 32,
       "open_chats_count": 77,
       "threads_count": 2,
       "messages_count": 54,
       "org_domain": "",
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "cover_photo_url": "",
       "icon_url": "",
       "group_url": "",
       "allow_parent_subs_to_post": false,
       "send_event_summaries": false,
       "event_summary_schedule": "event_summary_biweekly_friday",
       "send_invites_on_join": false,
       "perms": 
         {
          "object": "perms",
          "archives_visible": false,
          "polls_visible": false,
          "members_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
          "hashtags_visible": false,
          "guidelines_visible": false,
          "subgroups_visible": false,
          "open_donations_visible": false,
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": false,
          "create_hashtags": false,
          "manage_hashtags": false,
          "manage_integrations": false,
          "manage_group_settings": false,
          "make_moderator": false,
          "manage_member_subscription_options": false,
          "manage_pending_members": false,
          "remove_members": false,
          "ban_members": false,
          "manage_group_billing": false,
          "manage_group_payments": false,
          "edit_archives": false,
          "manage_pending_messages": false,
          "invite_members": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "manage_photos": false,
          "manage_members": false,
          "manage_calendar": false,
          "manage_chats": false,
          "view_member_directory": false,
          "manage_files": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
         },
       "email_address": "",
      }
    ],
    "tables": [
      {
       "id": 83,
       "object": "databasetable",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "group_id": 30,
       "user_id": 86,
       "name": "",
       "short_desc": "",
       "desc": "",
       "desc_type": "",
       "edit_table": "database_access_all",
       "edit_rows": "database_access_all",
       "add_rows": "database_access_all",
       "view_table": "database_access_all",
       "num_rows": 87,
       "max_row_id": 62,
       "num_columns": 4,
       "max_col_id": 21,
       "display_template": "",
       "columns": [
         {
          "id": 93,
          "name": "",
          "type": "address",
          "required": false,
          "color": "column_color_antique_pink",
          "choices": [""],
          "width": 98,
          "default_hidden": false,
          "description": "",
          "default_country": "",
         }
       ],
       "id_default_hidden": false,
       "updated_default_hidden": false,
      }
    ],
    "hashtags": [
      {
       "id": 56,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 65,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hashtag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 22,
       "last_message_date": "2009-11-10T15:00:00-08:00",
       "muted": false,
       "followed": false,
      }
    ],
   }
 ],
}
View Feed List definition

Example Error Response

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

Get Single Feed

Get a single feed object for a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.

GET /api/v1/getsinglefeed

$ curl "https://groups.io/api/v1/getsinglefeed?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "feed",
 "member_info": 
   {
    "id": 45,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 94,
    "group_id": 6,
    "group_name": "mygroup",
    "status": "sub_status_banned",
    "post_status": "sub_poststatus_allowed",
    "email_delivery": "email_delivery_digest",
    "message_selection": "message_selection_all",
    "auto_follow_replies": false,
    "max_attachment_size": "max_attachment_size_large",
    "approved_posts": 99,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_app_only",
    "pending_sub_notify": "sub_notify_app_only",
    "sub_notify": "sub_notify_app_only",
    "storage_notify": "sub_notify_app_only",
    "sub_group_notify": "sub_notify_app_only",
    "message_report_notify": "sub_notify_app_only",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "chat_notify": "sub_notify_app_only",
    "photo_notify": "sub_notify_app_only",
    "file_notify": "sub_notify_app_only",
    "wiki_notify": "sub_notify_app_only",
    "database_notify": "sub_notify_app_only",
    "email": "joe@example.com",
    "user_status": "user_status_bounced",
    "user_name": "joe",
    "timezone": "America/Los_Angeles",
    "full_name": "Joe Smith",
    "about_me": "",
    "location": "",
    "website": "https://example.com",
    "profile_photo_url": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "use_signature": false,
    "use_signature_email": false,
    "signature": "",
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "num_drafts": 24,
    "pending_subs": 20,
    "pending_msgs": 44,
    "cover_photo_url": "",
    "icon_url": "",
    "nice_group_name": "",
    "subs_count": 59,
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
   },
 "group": 
   {
    "id": 7,
    "object": "group",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "title": "The Example Group",
    "name": "example",
    "nice_group_name": "",
    "alias": "",
    "desc": "This is the description for the example group.",
    "plain_desc": "This is the description for the example group.",
    "subject_tag": "[example]",
    "footer": "",
    "website": "",
    "announce": false,
    "moderation": "moderate_first_message",
    "new_users_moderated": false,
    "unmoderate_users_after": 24,
    "restricted": false,
    "allow_non_subs_to_post": false,
    "force_html_emails": false,
    "normalize_html_emails": false,
    "reply_to": "group_reply_only_to_sender",
    "remove_other_reply_options": false,
    "privacy": "group_privacy_archives",
    "seperate_footers": false,
    "allow_downloads": "allow_downloads_by_members",
    "members_visible": "group_view_members_moderators",
    "subgroup_access": "sub_group_moderators",
    "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_limited",
    "chat_access": "group_access_limited",
    "handle_attachments": "group_attachments_bounced",
    "plain_text_only": false,
    "handle_virus": "handle_virus_block",
    "locked": false,
    "plan": "group_plan_basic",
    "trial_group": false,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 57,
    "org_id": 53,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 74,
    "max_number_of_reposts": 75,
    "email_delivery_default": "email_delivery_digest",
    "message_selection_default": "message_selection_all",
    "auto_follow_replies_default": false,
    "max_attachment_size_default": "max_attachment_size_large",
    "default_timezone": "",
    "default_time_pref": "military_time",
    "default_date_pref": "international_date",
    "default_monday_start": false,
    "disable_edits": false,
    "disable_no_email": false,
    "auto_close_threads": false,
    "close_threads_after": 40,
    "auto_moderate_threads": false,
    "moderate_threads_after": 89,
    "sticky_wiki_page_id": 14,
    "subgroupcategoryid": 45,
    "subs_count": 39,
    "pending_subs_count": 81,
    "pending_msgs_count": 31,
    "open_chats_count": 51,
    "threads_count": 85,
    "messages_count": 29,
    "org_domain": "",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "cover_photo_url": "",
    "icon_url": "",
    "group_url": "",
    "allow_parent_subs_to_post": false,
    "send_event_summaries": false,
    "event_summary_schedule": "event_summary_biweekly_friday",
    "send_invites_on_join": false,
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
    "email_address": "",
   },
 "topics": [
   {
    "topic": 
      {
       "id": 3,
       "object": "topic",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "group_id": 95,
       "group_subject_tag": "",
       "subject": "",
       "summary": "",
       "name": "",
       "profile_photo_url": "",
       "num_messages": 92,
       "is_sticky": false,
       "is_moderated": false,
       "is_closed": false,
       "has_attachments": false,
       "reply_to": "thread_reply_group_default",
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "hashtags": [
         {
          "id": 72,
          "object": "hashtag",
          "created": "2009-11-10T15:00:00-08:00",
          "group_id": 75,
          "name": "",
          "alias": 
            {
            },
          "mods_only_post": false,
          "mods_only_replies": false,
          "no_email": false,
          "moderated": false,
          "special": false,
          "replies_unmoderated": false,
          "locked": false,
          "until": "hashtag_delete_day",
          "close_instead_of_delete": false,
          "description": "",
          "color_name": "tag_antique_pink",
          "color_hex": "",
          "reply_to": "thread_reply_group_default",
          "topic_count": 77,
          "last_message_date": "2009-11-10T15:00:00-08:00",
          "muted": false,
          "followed": false,
         }
       ],
      },
    "images": [
      {
       "id": "",
       "object": "attachment",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 62,
       "user_id": 73,
       "thread_id": 17,
       "message_num": 59,
       "attach_num": 7,
       "type": "",
       "sub_type": "",
       "name": "",
       "content": "",
       "image_width": 80,
       "image_height": 5,
       "thumbnail_url": "",
      }
    ],
   }
 ],
 "events": [
   {
    "id": 6,
    "object": "event",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "creator_name": "@JohnSmith",
    "group_id": 74,
    "group_name": "",
    "nice_group_name": "",
    "start_time": "2009-11-10T15:00:00-08:00",
    "end_time": "2009-11-10T15:00:00-08:00",
    "timezone": "",
    "all_day": false,
    "name": "",
    "location": "",
    "description": "",
    "organizer_name": "",
    "organizer_email": "",
    "organizer_phone": "",
    "color_name": "tag_antique_pink",
    "color_hex": "",
    "rsvp": false,
    "max_attendees": 44,
    "additional_guests": false,
    "comment_label": "",
    "yes_message": "",
    "has_rsvp": false,
    "rsvp_type": "",
    "rsvp_comment": "",
    "rsvp_additional_guests": 23,
   }
 ],
 "files": [
   {
    "id": 94,
    "object": "file",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 22,
    "group_id": 33,
    "name": "",
    "desc": "",
    "size": 74,
    "path": "",
    "parent_folder_id": 10,
    "is_folder": false,
    "type": "",
    "count": 30,
    "media_type": "",
    "download_url": "",
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
   }
 ],
 "photos": [
   {
    "id": 95,
    "object": "photo",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 14,
    "group_id": 23,
    "name": "",
    "desc": "",
    "media_type": "image/jpeg",
    "size": 50,
    "attachment_num": 9,
    "width": 77,
    "height": 45,
    "album_id": 71,
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
    "format": "gif",
    "focal_length": 3.2,
    "iso": 8,
    "aperture": 3.2,
    "shutter_speed": 98,
    "taken": 34,
    "make": "",
    "model": "",
    "thumbnail_url": "",
    "download_url": "",
   }
 ],
 "chats": [
   {
    "id": 79,
    "object": "chat",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 54,
    "profile_photo_url": "",
    "name": "",
    "can_view_profile": false,
    "group_id": 21,
    "subject": "The chat subject",
    "desc": "This is the description of the chat",
    "is_closed": false,
    "num_messages": 87,
    "chat_sub": 
      {
       "id": 26,
       "object": "chat_sub",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 10,
       "group_id": 21,
       "chat_id": 67,
       "last_msg_seen": 1,
      },
   }
 ],
 "wikis": [
   {
    "id": 49,
    "object": "wiki_page",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 88,
    "group_id": 20,
    "title": "",
    "path": "",
    "locked": false,
    "rev_count": 74,
   }
 ],
 "subgroups": [
   {
    "id": 1,
    "object": "group",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "title": "The Example Group",
    "name": "example",
    "nice_group_name": "",
    "alias": "",
    "desc": "This is the description for the example group.",
    "plain_desc": "This is the description for the example group.",
    "subject_tag": "[example]",
    "footer": "",
    "website": "",
    "announce": false,
    "moderation": "moderate_first_message",
    "new_users_moderated": false,
    "unmoderate_users_after": 40,
    "restricted": false,
    "allow_non_subs_to_post": false,
    "force_html_emails": false,
    "normalize_html_emails": false,
    "reply_to": "group_reply_only_to_sender",
    "remove_other_reply_options": false,
    "privacy": "group_privacy_archives",
    "seperate_footers": false,
    "allow_downloads": "allow_downloads_by_members",
    "members_visible": "group_view_members_moderators",
    "subgroup_access": "sub_group_moderators",
    "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_limited",
    "chat_access": "group_access_limited",
    "handle_attachments": "group_attachments_bounced",
    "plain_text_only": false,
    "handle_virus": "handle_virus_block",
    "locked": false,
    "plan": "group_plan_basic",
    "trial_group": false,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 73,
    "org_id": 96,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 66,
    "max_number_of_reposts": 75,
    "email_delivery_default": "email_delivery_digest",
    "message_selection_default": "message_selection_all",
    "auto_follow_replies_default": false,
    "max_attachment_size_default": "max_attachment_size_large",
    "default_timezone": "",
    "default_time_pref": "military_time",
    "default_date_pref": "international_date",
    "default_monday_start": false,
    "disable_edits": false,
    "disable_no_email": false,
    "auto_close_threads": false,
    "close_threads_after": 10,
    "auto_moderate_threads": false,
    "moderate_threads_after": 72,
    "sticky_wiki_page_id": 13,
    "subgroupcategoryid": 14,
    "subs_count": 59,
    "pending_subs_count": 25,
    "pending_msgs_count": 46,
    "open_chats_count": 21,
    "threads_count": 44,
    "messages_count": 63,
    "org_domain": "",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "cover_photo_url": "",
    "icon_url": "",
    "group_url": "",
    "allow_parent_subs_to_post": false,
    "send_event_summaries": false,
    "event_summary_schedule": "event_summary_biweekly_friday",
    "send_invites_on_join": false,
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
    "email_address": "",
   }
 ],
 "tables": [
   {
    "id": 36,
    "object": "databasetable",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 87,
    "user_id": 88,
    "name": "",
    "short_desc": "",
    "desc": "",
    "desc_type": "",
    "edit_table": "database_access_all",
    "edit_rows": "database_access_all",
    "add_rows": "database_access_all",
    "view_table": "database_access_all",
    "num_rows": 23,
    "max_row_id": 25,
    "num_columns": 26,
    "max_col_id": 19,
    "display_template": "",
    "columns": [
      {
       "id": 0,
       "name": "",
       "type": "address",
       "required": false,
       "color": "column_color_antique_pink",
       "choices": [""],
       "width": 14,
       "default_hidden": false,
       "description": "",
       "default_country": "",
      }
    ],
    "id_default_hidden": false,
    "updated_default_hidden": false,
   }
 ],
 "hashtags": [
   {
    "id": 30,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 76,
    "name": "",
    "alias": 
      {
      },
    "mods_only_post": false,
    "mods_only_replies": false,
    "no_email": false,
    "moderated": false,
    "special": false,
    "replies_unmoderated": false,
    "locked": false,
    "until": "hashtag_delete_day",
    "close_instead_of_delete": false,
    "description": "",
    "color_name": "tag_antique_pink",
    "color_hex": "",
    "reply_to": "thread_reply_group_default",
    "topic_count": 0,
    "last_message_date": "2009-11-10T15:00:00-08:00",
    "muted": false,
    "followed": false,
   }
 ],
}
View Feed definition

Example Error Response

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

Files

These are the API endpoints for directories and files.

Get File Directory

Get file directory. Files and directories are returned using the pagination request and object format.

Permissions Needed

You must have the files_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
path
optional
string

Path to view. Path can either be empty or a folder.
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: title, created.
sort_dir
optional
string

Sort direction. Can be asc or desc.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a file list object if successful. Returns an error if there is an error.

Additional Errors
No additional errors
Notes

GET /api/v1/getfiledirectory

$ curl "https://groups.io/api/v1/getfiledirectory?group_id=12&path=%2FTop%2FNext" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 51,
 "start_item": 34,
 "end_item": 19,
 "has_more": false,
 "next_page_token": 66,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "path": "",
 "files_percentage": 13,
 "files_gigs": "",
 "data": [
   {
    "id": 45,
    "object": "file",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 41,
    "group_id": 42,
    "name": "",
    "desc": "",
    "size": 39,
    "path": "",
    "parent_folder_id": 94,
    "is_folder": false,
    "type": "",
    "count": 21,
    "media_type": "",
    "download_url": "",
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
   }
 ],
}
View File List definition

Example Error Response

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

Get File

Get file.

Permissions Needed

You must have the files_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
path
required
string

Path to file to download.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a file object if successful. Returns an error if there is an error.

Additional Errors
No additional errors
Notes

GET /api/v1/getfile

$ curl "https://groups.io/api/v1/getfile?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "id": 74,
 "object": "file",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 1,
 "group_id": 50,
 "name": "",
 "desc": "",
 "size": 85,
 "path": "",
 "parent_folder_id": 88,
 "is_folder": false,
 "type": "",
 "count": 64,
 "media_type": "",
 "download_url": "",
 "display_name": "",
 "user_name": "",
 "profile_photo_url": "",
 "profile_privacy": "",
 "email": "",
}
View File definition

Example Error Response

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

Search Files

Search files. Files and directory matches are returned using the pagination request and object format.

Permissions Needed

You must have the files_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
q
required
string

Query string.
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: title, created.
sort_dir
optional
string

Sort direction. Can be asc or desc.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a file list object if successful. Returns an error if there is an error.

Additional Errors
"bad_request"

"invalid query" is returned if the query string is empty.
Notes

GET /api/v1/searchfiles

$ curl "https://groups.io/api/v1/searchfiles?group_id=12&q=Search+Term" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 60,
 "start_item": 16,
 "end_item": 19,
 "has_more": false,
 "next_page_token": 82,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "path": "",
 "files_percentage": 16,
 "files_gigs": "",
 "data": [
   {
    "id": 13,
    "object": "file",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 16,
    "group_id": 22,
    "name": "",
    "desc": "",
    "size": 1,
    "path": "",
    "parent_folder_id": 55,
    "is_folder": false,
    "type": "",
    "count": 77,
    "media_type": "",
    "download_url": "",
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
   }
 ],
}
View File List definition

Example Error Response

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

Add Files

Add files. IN DEVELOPMENT. DO NOT USE YET.

Permissions Needed

You must have permission to add files to the folder.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
folder_id
required
number

ID of the folder to add the files to, or 0 if the top-level.
desc
optional
string

Description of the file.
fileupload
required
multipart file

Multipart file upload of one or more files.
is_folder
optional
boolean

If true, this is an upload of a folder. We will interpret filenames as full paths, using either / or \ as a separator. We will create folders as needed.
notify
optional
boolean

If true, send a notification to the group.
csrf
required
string

The csrf_token from the user object returned when first logged in.
Returns

Returns a file list object if successful. Returns an error if there is an error.

Additional Errors
"bad_request"

"invalid folder_id" is returned if the folder id is missing or invalid.
"bad_request"

"no space" is returned if the group is out of space.
"bad_request"

"too big" is returned if the file is too large.

POST /api/v1/addfiles

$ curl "https://groups.io/api/v1/addfiles" \
-b "cookies.curl"
-F fileupload=@path_to_file \
-F "folder_id=12" \
-F "csrf=12345"

Example Successful Response

 {
 "object": "list",
 "total_count": 63,
 "start_item": 17,
 "end_item": 58,
 "has_more": false,
 "next_page_token": 32,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "path": "",
 "files_percentage": 79,
 "files_gigs": "",
 "data": [
   {
    "id": 75,
    "object": "file",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 33,
    "group_id": 40,
    "name": "",
    "desc": "",
    "size": 27,
    "path": "",
    "parent_folder_id": 34,
    "is_folder": false,
    "type": "",
    "count": 52,
    "media_type": "",
    "download_url": "",
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
   }
 ],
}
View File List definition

Example Error Response

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

Group

Create Group

Create a group.

Permissions Needed

None.

POST Parameters
group_name
required
string

Name of the new group.
desc
required
string

Description of the new group.
privacy
required
string

Privacy of the new group, one of group_privacy_none, group_privacy_archives, group_privacy_unlisted, group_privacy_unlisted_public
csrf
required
string

The csrf_token from the user object returned when first logged in.
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
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns the group object if the group is successfully created. 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"

"invalid group_name" is returned if the group name is not a valid group name.
"bad_request"

"description too short" is returned if the group description is too short.
"bad_request"

"name already taken" is returned if a group with that name already exists.
Notes
  • A subscription is created for the user to the group with owner permissions. If email_delivery, message_selection, auto_follow_replies, or max_attachment_size is specified, the subscription will be created with those values.

POST /api/v1/creategroup

$ curl "https://groups.io/api/v1/creategroup" \
-b "cookies.curl" \
-d group_name=apisubgroup \
-d desc=This+is+my+group \
-d privacy=group_privacy_none \
-d csrf=12345

Example Successful Response

 {
 "id": 28,
 "object": "group",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "title": "The Example Group",
 "name": "example",
 "nice_group_name": "",
 "alias": "",
 "desc": "This is the description for the example group.",
 "plain_desc": "This is the description for the example group.",
 "subject_tag": "[example]",
 "footer": "",
 "website": "",
 "announce": false,
 "moderation": "moderate_first_message",
 "new_users_moderated": false,
 "unmoderate_users_after": 37,
 "restricted": false,
 "allow_non_subs_to_post": false,
 "force_html_emails": false,
 "normalize_html_emails": false,
 "reply_to": "group_reply_only_to_sender",
 "remove_other_reply_options": false,
 "privacy": "group_privacy_archives",
 "seperate_footers": false,
 "allow_downloads": "allow_downloads_by_members",
 "members_visible": "group_view_members_moderators",
 "subgroup_access": "sub_group_moderators",
 "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_limited",
 "chat_access": "group_access_limited",
 "handle_attachments": "group_attachments_bounced",
 "plain_text_only": false,
 "handle_virus": "handle_virus_block",
 "locked": false,
 "plan": "group_plan_basic",
 "trial_group": false,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 47,
 "org_id": 69,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 12,
 "max_number_of_reposts": 46,
 "email_delivery_default": "email_delivery_digest",
 "message_selection_default": "message_selection_all",
 "auto_follow_replies_default": false,
 "max_attachment_size_default": "max_attachment_size_large",
 "default_timezone": "",
 "default_time_pref": "military_time",
 "default_date_pref": "international_date",
 "default_monday_start": false,
 "disable_edits": false,
 "disable_no_email": false,
 "auto_close_threads": false,
 "close_threads_after": 9,
 "auto_moderate_threads": false,
 "moderate_threads_after": 4,
 "sticky_wiki_page_id": 56,
 "subgroupcategoryid": 14,
 "subs_count": 89,
 "pending_subs_count": 23,
 "pending_msgs_count": 42,
 "open_chats_count": 64,
 "threads_count": 39,
 "messages_count": 30,
 "org_domain": "",
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "cover_photo_url": "",
 "icon_url": "",
 "group_url": "",
 "allow_parent_subs_to_post": false,
 "send_event_summaries": false,
 "event_summary_schedule": "event_summary_biweekly_friday",
 "send_invites_on_join": false,
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "email_address": "",
}
View Group definition

Example Error Response

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

Create Sub Group

Create a subgroup.

Permissions Needed

You must have the manage_subgroups permission to use this call.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
sub_group_name
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
csrf
required
string

The csrf_token from the user object returned when first logged in.
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
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns the group object if the subgroup is successfully created. Returns an error if parameters are invalid (e.g. specifying an invalid sub_group_name). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid group_name" is returned if the group name is not a valid group nae.
"bad_request"

"description too short" is returned if the subgroup description is too short.
"bad_request"

"name already taken" is returned if a subgroup with that name already exists.
"bad_request"

"group is a subgroup" is returned if the group_id refers to a subgroup and not a parent group.
"bad_request"

"group does not support subgroups" is returned if the group is a free group.
Notes
  • A subscription is created for the user to the group with owner permissions. If email_delivery, message_selection, auto_follow_replies, or max_attachment_size is specified, the subscription will be created with those values.

POST /api/v1/createsubgroup

$ curl "https://groups.io/api/v1/createsubgroup" \
-b "cookies.curl" \
-d group_id=5 \
-d sub_group_name=apisubgroup \
-d desc=This+is+my+subgroup \
-d privacy=sub_group_privacy_none \
-d csrf=12345

Example Successful Response

 {
 "id": 19,
 "object": "group",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "title": "The Example Group",
 "name": "example",
 "nice_group_name": "",
 "alias": "",
 "desc": "This is the description for the example group.",
 "plain_desc": "This is the description for the example group.",
 "subject_tag": "[example]",
 "footer": "",
 "website": "",
 "announce": false,
 "moderation": "moderate_first_message",
 "new_users_moderated": false,
 "unmoderate_users_after": 53,
 "restricted": false,
 "allow_non_subs_to_post": false,
 "force_html_emails": false,
 "normalize_html_emails": false,
 "reply_to": "group_reply_only_to_sender",
 "remove_other_reply_options": false,
 "privacy": "group_privacy_archives",
 "seperate_footers": false,
 "allow_downloads": "allow_downloads_by_members",
 "members_visible": "group_view_members_moderators",
 "subgroup_access": "sub_group_moderators",
 "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_limited",
 "chat_access": "group_access_limited",
 "handle_attachments": "group_attachments_bounced",
 "plain_text_only": false,
 "handle_virus": "handle_virus_block",
 "locked": false,
 "plan": "group_plan_basic",
 "trial_group": false,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 60,
 "org_id": 94,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 85,
 "max_number_of_reposts": 21,
 "email_delivery_default": "email_delivery_digest",
 "message_selection_default": "message_selection_all",
 "auto_follow_replies_default": false,
 "max_attachment_size_default": "max_attachment_size_large",
 "default_timezone": "",
 "default_time_pref": "military_time",
 "default_date_pref": "international_date",
 "default_monday_start": false,
 "disable_edits": false,
 "disable_no_email": false,
 "auto_close_threads": false,
 "close_threads_after": 13,
 "auto_moderate_threads": false,
 "moderate_threads_after": 1,
 "sticky_wiki_page_id": 28,
 "subgroupcategoryid": 57,
 "subs_count": 84,
 "pending_subs_count": 62,
 "pending_msgs_count": 83,
 "open_chats_count": 21,
 "threads_count": 50,
 "messages_count": 15,
 "org_domain": "",
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "cover_photo_url": "",
 "icon_url": "",
 "group_url": "",
 "allow_parent_subs_to_post": false,
 "send_event_summaries": false,
 "event_summary_schedule": "event_summary_biweekly_friday",
 "send_invites_on_join": false,
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "email_address": "",
}
View Group definition

Example Error Response

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

Get Group Settings

Get the group settings

Permissions Needed

No permissions are needed, but some fields will not be returned if you do not have the proper permissions. For security reasons, you must specify a group_name to access information about a group that you are not subscribed to.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified, but group_id will be ignored if you are not subscribed to the group.
group_name
required
string

Name of the group. Either group_id or group_name must be specified, but group_id will be ignored if you are not subscribed to the group.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.

GET /api/v1/getgroup

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

Example Successful Response

 {
 "id": 40,
 "object": "group",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "title": "The Example Group",
 "name": "example",
 "nice_group_name": "",
 "alias": "",
 "desc": "This is the description for the example group.",
 "plain_desc": "This is the description for the example group.",
 "subject_tag": "[example]",
 "footer": "",
 "website": "",
 "announce": false,
 "moderation": "moderate_first_message",
 "new_users_moderated": false,
 "unmoderate_users_after": 92,
 "restricted": false,
 "allow_non_subs_to_post": false,
 "force_html_emails": false,
 "normalize_html_emails": false,
 "reply_to": "group_reply_only_to_sender",
 "remove_other_reply_options": false,
 "privacy": "group_privacy_archives",
 "seperate_footers": false,
 "allow_downloads": "allow_downloads_by_members",
 "members_visible": "group_view_members_moderators",
 "subgroup_access": "sub_group_moderators",
 "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_limited",
 "chat_access": "group_access_limited",
 "handle_attachments": "group_attachments_bounced",
 "plain_text_only": false,
 "handle_virus": "handle_virus_block",
 "locked": false,
 "plan": "group_plan_basic",
 "trial_group": false,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 42,
 "org_id": 91,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 98,
 "max_number_of_reposts": 1,
 "email_delivery_default": "email_delivery_digest",
 "message_selection_default": "message_selection_all",
 "auto_follow_replies_default": false,
 "max_attachment_size_default": "max_attachment_size_large",
 "default_timezone": "",
 "default_time_pref": "military_time",
 "default_date_pref": "international_date",
 "default_monday_start": false,
 "disable_edits": false,
 "disable_no_email": false,
 "auto_close_threads": false,
 "close_threads_after": 7,
 "auto_moderate_threads": false,
 "moderate_threads_after": 12,
 "sticky_wiki_page_id": 95,
 "subgroupcategoryid": 16,
 "subs_count": 52,
 "pending_subs_count": 83,
 "pending_msgs_count": 55,
 "open_chats_count": 69,
 "threads_count": 40,
 "messages_count": 94,
 "org_domain": "",
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "cover_photo_url": "",
 "icon_url": "",
 "group_url": "",
 "allow_parent_subs_to_post": false,
 "send_event_summaries": false,
 "event_summary_schedule": "event_summary_biweekly_friday",
 "send_invites_on_join": false,
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "email_address": "",
}
View Group definition

Example Error Response

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

Get Sub Groups

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. Either group_id or group_name must be specified.
group_name
required
string

Name of the parent group. Either group_id or group_name must be specified.
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 .
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.

GET /api/v1/getsubgroups

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

Example Successful Response

 {
 "object": "list",
 "total_count": 98,
 "start_item": 90,
 "end_item": 17,
 "has_more": false,
 "next_page_token": 82,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 14,
    "object": "group",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "title": "The Example Group",
    "name": "example",
    "nice_group_name": "",
    "alias": "",
    "desc": "This is the description for the example group.",
    "plain_desc": "This is the description for the example group.",
    "subject_tag": "[example]",
    "footer": "",
    "website": "",
    "announce": false,
    "moderation": "moderate_first_message",
    "new_users_moderated": false,
    "unmoderate_users_after": 70,
    "restricted": false,
    "allow_non_subs_to_post": false,
    "force_html_emails": false,
    "normalize_html_emails": false,
    "reply_to": "group_reply_only_to_sender",
    "remove_other_reply_options": false,
    "privacy": "group_privacy_archives",
    "seperate_footers": false,
    "allow_downloads": "allow_downloads_by_members",
    "members_visible": "group_view_members_moderators",
    "subgroup_access": "sub_group_moderators",
    "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_limited",
    "chat_access": "group_access_limited",
    "handle_attachments": "group_attachments_bounced",
    "plain_text_only": false,
    "handle_virus": "handle_virus_block",
    "locked": false,
    "plan": "group_plan_basic",
    "trial_group": false,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 82,
    "org_id": 68,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 76,
    "max_number_of_reposts": 26,
    "email_delivery_default": "email_delivery_digest",
    "message_selection_default": "message_selection_all",
    "auto_follow_replies_default": false,
    "max_attachment_size_default": "max_attachment_size_large",
    "default_timezone": "",
    "default_time_pref": "military_time",
    "default_date_pref": "international_date",
    "default_monday_start": false,
    "disable_edits": false,
    "disable_no_email": false,
    "auto_close_threads": false,
    "close_threads_after": 96,
    "auto_moderate_threads": false,
    "moderate_threads_after": 25,
    "sticky_wiki_page_id": 68,
    "subgroupcategoryid": 62,
    "subs_count": 43,
    "pending_subs_count": 51,
    "pending_msgs_count": 21,
    "open_chats_count": 13,
    "threads_count": 9,
    "messages_count": 93,
    "org_domain": "",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "cover_photo_url": "",
    "icon_url": "",
    "group_url": "",
    "allow_parent_subs_to_post": false,
    "send_event_summaries": false,
    "event_summary_schedule": "event_summary_biweekly_friday",
    "send_invites_on_join": false,
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
    "email_address": "",
   }
 ],
}
View Group List definition

Example Error Response

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

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. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
csrf
required
string

The csrf_token from the user object returned when first logged in.
title
optional
string

Title.
name
optional
string

New name for the group. If this is a subgroup, this needs to be of the form parentName+subName.
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, sub_group_privacy_unlisted_public_archives.
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, group_attachments_moderated
handle_virus
optional
string

Can be: handle_virus_block, handle_virus_moderate
plain_text_only
optional
boolean
fig_leaf
optional
string

Can be fig_leaf_archives, fig_leaf_none
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
hash_tag_permissions
optional
string

Can be: hash_tag_create_subs, hash_tag_create_mods_bounce, hash_tag_create_mods_remove
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
default_timezone
optional
string

Default timezone for new users. For groups with subgroups, only settable on the parent group. The timezone string should corresponding to a file in the IANA Time Zone database.
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
allow_reposts
optional
boolean

If true, members can repost messages. Only used with premium and enterprise groups.
min_days_between_reposts
optional
number

The minimum number of days between reposts.
max_number_of_reposts
optional
number

The maximum number of times a member can repost their message.
allow_parent_subs_to_post
optional
boolean
send_event_summaries
optional
boolean

If true, and a premium group, a summary email of upcoming events is sent out regularly.
event_summary_schedule
optional
string

Can be event_summary_weekly_friday, event_summary_monthly, event_summary_biweekly_friday.
send_invites_on_join
optional
boolean

If true, and a premium group, invites to all calendar events will be sent to new users, and a set of cancel events will be sent to users when they leave.
lock_group
optional
boolean

If true, and a premium group, locks the group, preventing any additional changes.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
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 group_name" is returned if it's a bad group name.
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.
  • A group that is not restricted cannot have a members_visible value of group_view_members_subs, unless it is a subgroup and the parent group is restricted.

POST /api/v1/updategroup

$ curl "https://groups.io/api/v1/updategroup" \
-b "cookies.curl" \
-d group_id=2 \
-d chat_access=group_access_limited \
-d csrf=12345

Example Successful Response

 {
 "id": 70,
 "object": "group",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "title": "The Example Group",
 "name": "example",
 "nice_group_name": "",
 "alias": "",
 "desc": "This is the description for the example group.",
 "plain_desc": "This is the description for the example group.",
 "subject_tag": "[example]",
 "footer": "",
 "website": "",
 "announce": false,
 "moderation": "moderate_first_message",
 "new_users_moderated": false,
 "unmoderate_users_after": 37,
 "restricted": false,
 "allow_non_subs_to_post": false,
 "force_html_emails": false,
 "normalize_html_emails": false,
 "reply_to": "group_reply_only_to_sender",
 "remove_other_reply_options": false,
 "privacy": "group_privacy_archives",
 "seperate_footers": false,
 "allow_downloads": "allow_downloads_by_members",
 "members_visible": "group_view_members_moderators",
 "subgroup_access": "sub_group_moderators",
 "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_limited",
 "chat_access": "group_access_limited",
 "handle_attachments": "group_attachments_bounced",
 "plain_text_only": false,
 "handle_virus": "handle_virus_block",
 "locked": false,
 "plan": "group_plan_basic",
 "trial_group": false,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 86,
 "org_id": 41,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 90,
 "max_number_of_reposts": 98,
 "email_delivery_default": "email_delivery_digest",
 "message_selection_default": "message_selection_all",
 "auto_follow_replies_default": false,
 "max_attachment_size_default": "max_attachment_size_large",
 "default_timezone": "",
 "default_time_pref": "military_time",
 "default_date_pref": "international_date",
 "default_monday_start": false,
 "disable_edits": false,
 "disable_no_email": false,
 "auto_close_threads": false,
 "close_threads_after": 85,
 "auto_moderate_threads": false,
 "moderate_threads_after": 1,
 "sticky_wiki_page_id": 58,
 "subgroupcategoryid": 18,
 "subs_count": 92,
 "pending_subs_count": 35,
 "pending_msgs_count": 15,
 "open_chats_count": 81,
 "threads_count": 48,
 "messages_count": 56,
 "org_domain": "",
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "cover_photo_url": "",
 "icon_url": "",
 "group_url": "",
 "allow_parent_subs_to_post": false,
 "send_event_summaries": false,
 "event_summary_schedule": "event_summary_biweekly_friday",
 "send_invites_on_join": false,
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "email_address": "",
}
View Group definition

Example Error Response

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

Delete Group

Delete a group or a subgroup.

Permissions Needed

You must have the delete_group permission to use this call.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
understand
required
string

The string "I understand".
csrf
required
string

The csrf_token from the user object returned when first logged in.
reason
optional
string

A reason for deleting the group.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

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"

"understand" is returned if the proper string isn't passed in with the understand POST parameter.
Notes
  • Delete is permanent.
  • If the group has subgroups, all subgroups are also deleted.
  • If the group is not a subgroup (ie is a parent group or a stand alone group), the group name will not be recycled for some time and cannot be used again.

POST /api/v1/deletegroup

$ curl "https://groups.io/api/v1/deletegroup" \
-b "cookies.curl" \
-d group_id=2 \
-d understand=I+understand \
-d csrf=12345

Successful Response

HTTP 200

Example Error Response

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

Get Permissions

Return which permissions you have in a group. 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. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.

GET /api/v1/getperms

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

Example Successful Response

 {
 "object": "perms",
 "archives_visible": false,
 "polls_visible": false,
 "members_visible": false,
 "chat_visible": false,
 "calendar_visible": false,
 "files_visible": false,
 "database_visible": false,
 "photos_visible": false,
 "wiki_visible": false,
 "member_directory_visible": false,
 "hashtags_visible": false,
 "guidelines_visible": false,
 "subgroups_visible": false,
 "open_donations_visible": false,
 "manage_subgroups": false,
 "delete_group": false,
 "download_archives": false,
 "download_entire_group": false,
 "download_members": false,
 "view_activity": false,
 "create_hashtags": false,
 "manage_hashtags": false,
 "manage_integrations": false,
 "manage_group_settings": false,
 "make_moderator": false,
 "manage_member_subscription_options": false,
 "manage_pending_members": false,
 "remove_members": false,
 "ban_members": false,
 "manage_group_billing": false,
 "manage_group_payments": false,
 "edit_archives": false,
 "manage_pending_messages": false,
 "invite_members": false,
 "can_post": false,
 "can_vote": false,
 "manage_polls": false,
 "manage_photos": false,
 "manage_members": false,
 "manage_calendar": false,
 "manage_chats": false,
 "view_member_directory": false,
 "manage_files": false,
 "manage_wiki": false,
 "manage_subscription": false,
 "public_page": false,
 "sub_page": false,
 "mod_page": false,
}
View Perms definition

Example Error Response

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

Get Group Aliases

Get a group's aliases.

Permissions Needed

You must have the manage_group_settings permission to use this call.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
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.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Notes
  • Aliases are only available for premium and enterprise groups.
  • The group that an alias points to is identified by the alias_group_id field in the Group Alias object returned.

GET /api/v1/getgroupaliases

$ curl "https://groups.io/api/v1/getgroupaliases?group_id=5" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 17,
 "start_item": 74,
 "end_item": 99,
 "has_more": false,
 "next_page_token": 73,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 51,
    "object": "groupalias",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "name": "example",
    "alias_group_id": 61,
   }
 ],
}
View Group Alias List definition

Example Error Response

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

Add New Group Alias

Add a new group alias.

Permissions Needed

You must have the manage_group_settings permission to use this call. Also, the group having the alias added to must be a premium or enterprise group.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
alias_name
required
string

Name of the alias to create.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns the group object if the group is successfully created. 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

"invalid alias_name" is returned if the alias name is not a valid group name.
bad_request

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

POST /api/v1/newgroupalias

$ curl "https://groups.io/api/v1/newgroupalias" \
-b "cookies.curl" \
-d group_id=65 \
-d alias_name=newalias \
-d csrf=12345

Example Successful Response

 {
 "id": 60,
 "object": "group",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "title": "The Example Group",
 "name": "example",
 "nice_group_name": "",
 "alias": "",
 "desc": "This is the description for the example group.",
 "plain_desc": "This is the description for the example group.",
 "subject_tag": "[example]",
 "footer": "",
 "website": "",
 "announce": false,
 "moderation": "moderate_first_message",
 "new_users_moderated": false,
 "unmoderate_users_after": 92,
 "restricted": false,
 "allow_non_subs_to_post": false,
 "force_html_emails": false,
 "normalize_html_emails": false,
 "reply_to": "group_reply_only_to_sender",
 "remove_other_reply_options": false,
 "privacy": "group_privacy_archives",
 "seperate_footers": false,
 "allow_downloads": "allow_downloads_by_members",
 "members_visible": "group_view_members_moderators",
 "subgroup_access": "sub_group_moderators",
 "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_limited",
 "chat_access": "group_access_limited",
 "handle_attachments": "group_attachments_bounced",
 "plain_text_only": false,
 "handle_virus": "handle_virus_block",
 "locked": false,
 "plan": "group_plan_basic",
 "trial_group": false,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 24,
 "org_id": 14,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 18,
 "max_number_of_reposts": 63,
 "email_delivery_default": "email_delivery_digest",
 "message_selection_default": "message_selection_all",
 "auto_follow_replies_default": false,
 "max_attachment_size_default": "max_attachment_size_large",
 "default_timezone": "",
 "default_time_pref": "military_time",
 "default_date_pref": "international_date",
 "default_monday_start": false,
 "disable_edits": false,
 "disable_no_email": false,
 "auto_close_threads": false,
 "close_threads_after": 35,
 "auto_moderate_threads": false,
 "moderate_threads_after": 48,
 "sticky_wiki_page_id": 50,
 "subgroupcategoryid": 40,
 "subs_count": 52,
 "pending_subs_count": 90,
 "pending_msgs_count": 66,
 "open_chats_count": 99,
 "threads_count": 60,
 "messages_count": 94,
 "org_domain": "",
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "cover_photo_url": "",
 "icon_url": "",
 "group_url": "",
 "allow_parent_subs_to_post": false,
 "send_event_summaries": false,
 "event_summary_schedule": "event_summary_biweekly_friday",
 "send_invites_on_join": false,
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "email_address": "",
}
View Group definition

Example Error Response

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

Delete Group Alias

Delete a group alias.

Permissions Needed

You must have the manage_group_settings permission to use this call.

POST Parameters
alias_group_id
required
numer

ID of the alias group object to delete. Either alias_group_id or alias_group_name must be specified.
alias_group_name
required
string

Name of the alias group object to delete. Either alias_group_id or alias_group_name must be specified.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns the aliased group object if the alias is successfully deleted. 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

"invalid alias_group_name" is returned if the alias name is not a valid alias.
Notes

POST /api/v1/deletegroupalias

$ curl "https://groups.io/api/v1/deletegroupalias" \
-b "cookies.curl" \
-d alias_group_id=65 \
-d csrf=12345

Example Successful Response

 {
 "id": 10,
 "object": "group",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "title": "The Example Group",
 "name": "example",
 "nice_group_name": "",
 "alias": "",
 "desc": "This is the description for the example group.",
 "plain_desc": "This is the description for the example group.",
 "subject_tag": "[example]",
 "footer": "",
 "website": "",
 "announce": false,
 "moderation": "moderate_first_message",
 "new_users_moderated": false,
 "unmoderate_users_after": 51,
 "restricted": false,
 "allow_non_subs_to_post": false,
 "force_html_emails": false,
 "normalize_html_emails": false,
 "reply_to": "group_reply_only_to_sender",
 "remove_other_reply_options": false,
 "privacy": "group_privacy_archives",
 "seperate_footers": false,
 "allow_downloads": "allow_downloads_by_members",
 "members_visible": "group_view_members_moderators",
 "subgroup_access": "sub_group_moderators",
 "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_limited",
 "chat_access": "group_access_limited",
 "handle_attachments": "group_attachments_bounced",
 "plain_text_only": false,
 "handle_virus": "handle_virus_block",
 "locked": false,
 "plan": "group_plan_basic",
 "trial_group": false,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 66,
 "org_id": 1,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 22,
 "max_number_of_reposts": 60,
 "email_delivery_default": "email_delivery_digest",
 "message_selection_default": "message_selection_all",
 "auto_follow_replies_default": false,
 "max_attachment_size_default": "max_attachment_size_large",
 "default_timezone": "",
 "default_time_pref": "military_time",
 "default_date_pref": "international_date",
 "default_monday_start": false,
 "disable_edits": false,
 "disable_no_email": false,
 "auto_close_threads": false,
 "close_threads_after": 34,
 "auto_moderate_threads": false,
 "moderate_threads_after": 13,
 "sticky_wiki_page_id": 62,
 "subgroupcategoryid": 98,
 "subs_count": 17,
 "pending_subs_count": 93,
 "pending_msgs_count": 40,
 "open_chats_count": 53,
 "threads_count": 18,
 "messages_count": 1,
 "org_domain": "",
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "cover_photo_url": "",
 "icon_url": "",
 "group_url": "",
 "allow_parent_subs_to_post": false,
 "send_event_summaries": false,
 "event_summary_schedule": "event_summary_biweekly_friday",
 "send_invites_on_join": false,
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
 "email_address": "",
}
View Group definition

Example Error Response

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

Hashtags

New Hashtag

Create a new hashtag.

Permissions Needed

You must have the create_hashtags permission to use this call with a group.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
csrf
required
string

The csrf_token from the user object returned when first logged in.
name
required
string

Name of the hashtag, should begin with #.
description
optional
string

Description of the hashtag.
no_email
optional
boolean

If true, messages with this tag will not be emailed to the group.
reply_to
required
string

How replies to these messages are handled. Can be one of: thread_reply_group_default, thread_reply_to_group, thread_reply_to_sender, thread_reply_to_moderators, thread_reply_to_group_and_sender, thread_reply_only_to_sender
until
required
string

When set, tagged topics will automatically be deleted or locked after the specified time period. Can be one of: hashtag_delete_forever, hashtag_delete_hour, hashtag_delete_day, hashtag_delete_week, hashtag_delete_month, hashtag_delete_year
color
required
string

Color of the tag. Can be one of:
mods_only_post
optional
boolean

If true, only moderators can tag topics with this hashtag.
mods_only_replies
optional
boolean

If true, only moderators can reply to topics tagged with this hashtag.
close_instead
optional
boolean

If true, topics will be locked instead of deleted after the specified time period.
moderated
optional
boolean

If true, messages with this hashtag will be moderated.
locked
optional
boolean

If true, topics created with this hashtag will be locked immediately.
alias
optional
string

If specified, this hashtag is an alias of the named hashtag.
replies_unmoderated
optional
boolean

In moderated groups, if this is true replies to these messages are not moderated.
special
optional
boolean

If true, messages with this tag will be sent as special notices.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a chat object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid group_id" is returned if the group id is missing or invalid.
"bad_request"

"invalid name" is returned if the name is missing or invalid.
"bad_request"

"name exists" is returned if a hashtag with that name already exists.
"bad_request"

"invalid reply_to" is returned if the reply_to is missing or invalid.
"bad_request"

"invalid until" is returned if the until is missing or invalid.
"bad_request"

"invalid color" is returned if the color is missing or invalid.

POST /api/v1/newhashtag

$ curl "https://groups.io/api/v1/newhashtag" \
-b "cookies.curl" \
-d group_id=12&name=#Test&csrf=1234

Example Successful Response

 {
 "id": 6,
 "object": "hashtag",
 "created": "2009-11-10T15:00:00-08:00",
 "group_id": 88,
 "name": "",
 "alias": 
   {
   },
 "mods_only_post": false,
 "mods_only_replies": false,
 "no_email": false,
 "moderated": false,
 "special": false,
 "replies_unmoderated": false,
 "locked": false,
 "until": "hashtag_delete_day",
 "close_instead_of_delete": false,
 "description": "",
 "color_name": "tag_antique_pink",
 "color_hex": "",
 "reply_to": "thread_reply_group_default",
 "topic_count": 71,
 "last_message_date": "2009-11-10T15:00:00-08:00",
 "muted": false,
 "followed": false,
}
View Hashtag definition

Example Error Response

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

Update Hashtag

Update an existing hashtag.

Permissions Needed

You must have the manage_hashtags permission to use this call with a group.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
csrf
required
string

The csrf_token from the user object returned when first logged in.
name
required
string

Name of the hashtag, should begin with #.
new_name
optional
string

New name of the hashtag, should begin with #.
description
optional
string

Description of the hashtag.
no_email
optional
boolean

If true, messages with this tag will not be emailed to the group.
reply_to
optional
string

How replies to these messages are handled. Can be one of: thread_reply_group_default, thread_reply_to_group, thread_reply_to_sender, thread_reply_to_moderators, thread_reply_to_group_and_sender, thread_reply_only_to_sender
until
optional
string

When set, tagged topics will automatically be deleted or locked after the specified time period. Can be one of: hashtag_delete_forever, hashtag_delete_hour, hashtag_delete_day, hashtag_delete_week, hashtag_delete_month, hashtag_delete_year
color
optional
string

Color of the tag. Can be one of:
mods_only_post
optional
boolean

If true, only moderators can tag topics with this hashtag.
mods_only_replies
optional
boolean

If true, only moderators can reply to topics tagged with this hashtag.
close_instead
optional
boolean

If true, topics will be locked instead of deleted after the specified time period.
moderated
optional
boolean

If true, messages with this hashtag will be moderated.
locked
optional
boolean

If true, topics created with this hashtag will be locked immediately.
alias
optional
string

If specified, this hashtag is an alias of the named hashtag.
replies_unmoderated
optional
boolean

In moderated groups, if this is true replies to these messages are not moderated.
special
optional
boolean

If true, messages with this tag will be sent as special notices.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a chat object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid group_id" is returned if the group id is missing or invalid.
"bad_request"

"invalid name" is returned if the name is missing or invalid.
"bad_request"

"name exists" is returned if a hashtag with that name already exists.
"bad_request"

"invalid reply_to" is returned if the reply_to is missing or invalid.
"bad_request"

"invalid until" is returned if the until is missing or invalid.
"bad_request"

"invalid color" is returned if the color is missing or invalid.

POST /api/v1/updatehashtag

$ curl "https://groups.io/api/v1/updatehashtag" \
-b "cookies.curl" \
-d group_id=12&name=#Test&csrf=1234

Example Successful Response

 {
 "id": 77,
 "object": "hashtag",
 "created": "2009-11-10T15:00:00-08:00",
 "group_id": 42,
 "name": "",
 "alias": 
   {
   },
 "mods_only_post": false,
 "mods_only_replies": false,
 "no_email": false,
 "moderated": false,
 "special": false,
 "replies_unmoderated": false,
 "locked": false,
 "until": "hashtag_delete_day",
 "close_instead_of_delete": false,
 "description": "",
 "color_name": "tag_antique_pink",
 "color_hex": "",
 "reply_to": "thread_reply_group_default",
 "topic_count": 17,
 "last_message_date": "2009-11-10T15:00:00-08:00",
 "muted": false,
 "followed": false,
}
View Hashtag definition

Example Error Response

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

Get Hashtags

Get hashtags

Permissions Needed

You must have the hashtags_visible permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
usable_only
optional
boolean

If true, only return hashtags that the person has permission to use.
exclude_aliases
optional
boolean

If true, exclude hashtags that have been aliased to other hashtags.
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.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a hashtag list object if successful. Returns an error if there is an error.

Additional Errors
No additional errors

GET /api/v1/gethashtags

$ curl "https://groups.io/api/v1/gethashtags" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 7,
 "start_item": 84,
 "end_item": 50,
 "has_more": false,
 "next_page_token": 7,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 22,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 45,
    "name": "",
    "alias": 
      {
      },
    "mods_only_post": false,
    "mods_only_replies": false,
    "no_email": false,
    "moderated": false,
    "special": false,
    "replies_unmoderated": false,
    "locked": false,
    "until": "hashtag_delete_day",
    "close_instead_of_delete": false,
    "description": "",
    "color_name": "tag_antique_pink",
    "color_hex": "",
    "reply_to": "thread_reply_group_default",
    "topic_count": 35,
    "last_message_date": "2009-11-10T15:00:00-08:00",
    "muted": false,
    "followed": false,
   }
 ],
}
View Hashtag List definition

Example Error Response

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

Delete Hashtag

Delete a hashtag.

Permissions Needed

You must have the manage_hashtags permission to use this call with a group.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
csrf
required
string

The csrf_token from the user object returned when first logged in.
name
required
string

Name of the hashtag, should begin with #.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Additional Errors
"bad_request"

"invalid group_id" is returned if the group id is missing or invalid.
"bad_request"

"invalid name" is returned if the name is missing or invalid.

POST /api/v1/deletehashtag

$ curl "https://groups.io/api/v1/deletehashtag" \
-b "cookies.curl" \
-d group_id=12&name=#Test&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Mute Hashtag

Mute a hashtag.

Permissions Needed

You must be subscribed to the group.

POST Parameters
hashtag
required
string

Hashtag to mute.
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
until
required
string

How long to mute the hashtag for, can be mute_hour, mute_day, mute_week, mute_month, mute_forever.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Additional Errors
"bad_request"

"invalid until" is returned if the until value is invalid.

POST /api/v1/mutehashtag

$ curl "https://groups.io/api/v1/mutehashtag" \
-b "cookies.curl" \
-d hashtag=#test&group_id=12&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Unmute Hashtag

Unmute a hashtag.

Permissions Needed

You must be subscribed to the group.

POST Parameters
hashtag
required
string

Hashtag to unmute.
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Additional Errors
"bad_request"

"not muting hashtag" is returned if you are not currently muting this hashtag.

POST /api/v1/unmutehashtag

$ curl "https://groups.io/api/v1/unmutehashtag" \
-b "cookies.curl" \
-d hashtag=#test&group_id=12&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Follow Hashtag

Follow a hashtag.

Permissions Needed

You must be subscribed to the group.

POST Parameters
hashtag
required
string

Hashtag to follow.
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
until
required
string

How long to follow the hashtag for, can be mute_hour, mute_day, mute_week, mute_month, mute_forever.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Additional Errors
"bad_request"

"invalid until" is returned if the until value is invalid.

POST /api/v1/followhashtag

$ curl "https://groups.io/api/v1/followhashtag" \
-b "cookies.curl" \
-d hashtag=#test&group_id=12&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Unfollow Hashtag

Unfollow a hashtag.

Permissions Needed

You must be subscribed to the group.

POST Parameters
hashtag
required
string

Hashtag to unfollow.
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Additional Errors
"bad_request"

"not following hashtag" is returned if you are not currently following this hashtag.

POST /api/v1/unfollowhashtag

$ curl "https://groups.io/api/v1/unfollowhashtag" \
-b "cookies.curl" \
-d hashtag=#test&group_id=12&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Login

Login

Authenticate a user and return a login object, including HTTP cookies that are 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.
twofactor
optional
number

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

If true, use token based login instead of cookie based login. With token based logins, some features of the API are not available, like chat.
Returns

Returns a login object if a valid email address/password pair is provided. In addition, one or more HTTP cookies are set in the response. 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.

POST /api/v1/login

$ curl "https://groups.io/api/v1/login" \
-c "cookies.curl" \
-d email=test@example.com&password=qwerty

Example Successful Response

 {
 "user": 
   {
    "id": 48,
    "object": "user",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "email": "user@example.com",
    "full_name": "",
    "user_name": "",
    "timezone": "",
    "status": "user_status_bounced",
    "profile_photo_url": "",
    "post_pref": "",
    "per_page_pref": "",
    "allow_facebook_login": false,
    "allow_google_login": false,
    "allow_sso_login": false,
    "csrf_token": "",
    "two_factor_enabled": false,
    "recovery_codes": "",
    "dont_munge_message_id": false,
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "time_pref": "",
    "date_pref": "",
    "monday_start": false,
    "profile_privacy": "",
    "default_message_view": "expanded_message_view",
    "topics_sort_dir": "",
    "topic_sort_dir": "",
    "messages_sort_dir": "",
    "expanded_messages_sort_dir": "",
    "search_sort": "",
    "search_sort_dir": "",
    "photos_order_by": "",
    "photos_sort_dir": "",
    "album_order_by": "",
    "album_sort_dir": "",
    "default_calendar_view": "",
    "default_hashtag_view": "",
    "default_rsvp_view": "",
    "home_page": "home_page_calendar",
    "subscriptions": [
      {
       "id": 30,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 4,
       "group_id": 62,
       "group_name": "mygroup",
       "status": "sub_status_banned",
       "post_status": "sub_poststatus_allowed",
       "email_delivery": "email_delivery_digest",
       "message_selection": "message_selection_all",
       "auto_follow_replies": false,
       "max_attachment_size": "max_attachment_size_large",
       "approved_posts": 52,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_app_only",
       "pending_sub_notify": "sub_notify_app_only",
       "sub_notify": "sub_notify_app_only",
       "storage_notify": "sub_notify_app_only",
       "sub_group_notify": "sub_notify_app_only",
       "message_report_notify": "sub_notify_app_only",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "chat_notify": "sub_notify_app_only",
       "photo_notify": "sub_notify_app_only",
       "file_notify": "sub_notify_app_only",
       "wiki_notify": "sub_notify_app_only",
       "database_notify": "sub_notify_app_only",
       "email": "joe@example.com",
       "user_status": "user_status_bounced",
       "user_name": "joe",
       "timezone": "America/Los_Angeles",
       "full_name": "Joe Smith",
       "about_me": "",
       "location": "",
       "website": "https://example.com",
       "profile_photo_url": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "use_signature": false,
       "use_signature_email": false,
       "signature": "",
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "num_drafts": 75,
       "pending_subs": 14,
       "pending_msgs": 7,
       "cover_photo_url": "",
       "icon_url": "",
       "nice_group_name": "",
       "subs_count": 53,
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "perms": 
         {
          "object": "perms",
          "archives_visible": false,
          "polls_visible": false,
          "members_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
          "hashtags_visible": false,
          "guidelines_visible": false,
          "subgroups_visible": false,
          "open_donations_visible": false,
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": false,
          "create_hashtags": false,
          "manage_hashtags": false,
          "manage_integrations": false,
          "manage_group_settings": false,
          "make_moderator": false,
          "manage_member_subscription_options": false,
          "manage_pending_members": false,
          "remove_members": false,
          "ban_members": false,
          "manage_group_billing": false,
          "manage_group_payments": false,
          "edit_archives": false,
          "manage_pending_messages": false,
          "invite_members": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "manage_photos": false,
          "manage_members": false,
          "manage_calendar": false,
          "manage_chats": false,
          "view_member_directory": false,
          "manage_files": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
         },
      }
    ],
   },
 "token": "aabbffed2213234",
}
View Login definition

Example Error Response

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

Get Enterprise Info

Return information about an enterprise group.

Query Parameters
domain
required
string

Domain of the enterprise group.
Returns

Returns the enterprise info object. Returns an error if parameters are invalid (e.g. specifying an invalid domain). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid domain" is returned if the domain is missing or invalid.

GET /api/v1/enterpriseinfo

$ curl "https://groups.io/api/v1/getenterpriseinfo?domain=groups.example.com"

Successful Response

HTTP 200

Example Error Response

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

Logout

Clear all cookies associated with authentication.

Returns

Returns HTTP 200 on success.

GET /api/v1/logout

$ curl "https://groups.io/api/v1/logout"

Successful Response

HTTP 200

Example Error Response

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

Facebook Login Start

Start the Facebook login process.

Returns

Returns an oauth login object. Returns an error otherwise.

GET /api/v1/facebookloginstart

$ curl "https://groups.io/api/v1/facebookloginstart"

Example Successful Response

 {
 "object": "oauth_login",
 "state": "12345",
 "web_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "ios_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "android_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "scopes": ["user"],
}
View Oauth Login definition

Example Error Response

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

Facebook Login Final

Complete the Facebook login process. If the email address returned by Facebook matches an existing Groups.io user, then that user is logged in. If it does not match an existing user, a new user is created and logged in.

POST Parameters
state
required
string

Returned from earlier call to /facebookloginstart.
code
required
string

Returned from Facebook. Either code or access_token is required. If code is specified, we will exchange it for an access_token.
access_token
required
string

The access token from Facebook. Either code or access_token is required.
Returns

Returns a login object if a valid code and state are present. In addition, one or more HTTP cookies are set in the response. Returns an error otherwise.

Additional Errors
"bad_request"

"invalid state" is returned if the state parameter is invalid or missing.
"bad_request"

"invalid code or access_token" is returned if the code and access_token parameters are invalid or missing.
"bad_request"

"expired code" is returned if the code parameter is expired. Start the process over in this case.
"bad_request"

"inactive user" is returned if the user has been disabled.
"bad_request"

"invalid email address" is returned if the email address returned by Facebook is empty or invalid.
"bad_request"

"two factor enabled" is returned if the user has two-factor authentication enabled, which prevents Facebook logins.
"bad_request"

"facebook login prevented" is returned if the user has disabled Facebook logins. When this error is returned, an email is sent to the user with a link to enable Facebook logins.

POST /api/v1/facebookloginfinal

$ curl "https://groups.io/api/v1/facebookloginfinal \"
-c "cookies.curl" \
-d code=xxx&state=yyy

Example Successful Response

 {
 "user": 
   {
    "id": 99,
    "object": "user",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "email": "user@example.com",
    "full_name": "",
    "user_name": "",
    "timezone": "",
    "status": "user_status_bounced",
    "profile_photo_url": "",
    "post_pref": "",
    "per_page_pref": "",
    "allow_facebook_login": false,
    "allow_google_login": false,
    "allow_sso_login": false,
    "csrf_token": "",
    "two_factor_enabled": false,
    "recovery_codes": "",
    "dont_munge_message_id": false,
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "time_pref": "",
    "date_pref": "",
    "monday_start": false,
    "profile_privacy": "",
    "default_message_view": "expanded_message_view",
    "topics_sort_dir": "",
    "topic_sort_dir": "",
    "messages_sort_dir": "",
    "expanded_messages_sort_dir": "",
    "search_sort": "",
    "search_sort_dir": "",
    "photos_order_by": "",
    "photos_sort_dir": "",
    "album_order_by": "",
    "album_sort_dir": "",
    "default_calendar_view": "",
    "default_hashtag_view": "",
    "default_rsvp_view": "",
    "home_page": "home_page_calendar",
    "subscriptions": [
      {
       "id": 15,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 75,
       "group_id": 43,
       "group_name": "mygroup",
       "status": "sub_status_banned",
       "post_status": "sub_poststatus_allowed",
       "email_delivery": "email_delivery_digest",
       "message_selection": "message_selection_all",
       "auto_follow_replies": false,
       "max_attachment_size": "max_attachment_size_large",
       "approved_posts": 40,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_app_only",
       "pending_sub_notify": "sub_notify_app_only",
       "sub_notify": "sub_notify_app_only",
       "storage_notify": "sub_notify_app_only",
       "sub_group_notify": "sub_notify_app_only",
       "message_report_notify": "sub_notify_app_only",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "chat_notify": "sub_notify_app_only",
       "photo_notify": "sub_notify_app_only",
       "file_notify": "sub_notify_app_only",
       "wiki_notify": "sub_notify_app_only",
       "database_notify": "sub_notify_app_only",
       "email": "joe@example.com",
       "user_status": "user_status_bounced",
       "user_name": "joe",
       "timezone": "America/Los_Angeles",
       "full_name": "Joe Smith",
       "about_me": "",
       "location": "",
       "website": "https://example.com",
       "profile_photo_url": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "use_signature": false,
       "use_signature_email": false,
       "signature": "",
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "num_drafts": 60,
       "pending_subs": 39,
       "pending_msgs": 93,
       "cover_photo_url": "",
       "icon_url": "",
       "nice_group_name": "",
       "subs_count": 51,
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "perms": 
         {
          "object": "perms",
          "archives_visible": false,
          "polls_visible": false,
          "members_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
          "hashtags_visible": false,
          "guidelines_visible": false,
          "subgroups_visible": false,
          "open_donations_visible": false,
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": false,
          "create_hashtags": false,
          "manage_hashtags": false,
          "manage_integrations": false,
          "manage_group_settings": false,
          "make_moderator": false,
          "manage_member_subscription_options": false,
          "manage_pending_members": false,
          "remove_members": false,
          "ban_members": false,
          "manage_group_billing": false,
          "manage_group_payments": false,
          "edit_archives": false,
          "manage_pending_messages": false,
          "invite_members": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "manage_photos": false,
          "manage_members": false,
          "manage_calendar": false,
          "manage_chats": false,
          "view_member_directory": false,
          "manage_files": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
         },
      }
    ],
   },
 "token": "aabbffed2213234",
}
View Login definition

Example Error Response

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

Apple Login Start

Start the Apple login process.

Returns

Returns an oauth login object. Returns an error otherwise.

GET /api/v1/appleloginstart

$ curl "https://groups.io/api/v1/appleloginstart"

Example Successful Response

 {
 "object": "oauth_login",
 "state": "12345",
 "web_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "ios_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "android_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "scopes": ["user"],
}
View Oauth Login definition

Example Error Response

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

Google Login Start

Start the Google login process.

Returns

Returns an oauth login object. Returns an error otherwise.

GET /api/v1/googleloginstart

$ curl "https://groups.io/api/v1/googleloginstart"

Example Successful Response

 {
 "object": "oauth_login",
 "state": "12345",
 "web_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "ios_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "android_client_id": "EAAV5drZBzQ3IBALC8Wt86UsiAa0dK95svJU32FQusEIqeHZC",
 "scopes": ["user"],
}
View Oauth Login definition

Example Error Response

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

Apple Login Final

Complete the Apple login process. If the email address returned by Apple matches an existing Groups.io user, then that user is logged in. If it does not match an existing user, a new user is created and logged in.

POST Parameters
state
required
string

Returned from Apple.
code
required
string

Returned from Apple. Either code or access_token is required. If code is specified, we will exchange it for an access_token.
access_token
required
string

The access token from Apple. Either code or access_token is required.
Returns

Returns a login object if a valid code and state are present. In addition, one or more HTTP cookies are set in the response. Returns an error otherwise.

Additional Errors
"bad_request"

"invalid state" is returned if the state parameter is invalid or missing.
"bad_request"

"invalid code" is returned if the code parameter is invalid or missing.
"bad_request"

"inactive user" is returned if the user has been disabled.
"bad_request"

"two factor enabled" is returned if the user has two-factor authentication enabled, which prevents Apple logins.
"bad_request"

"invalid email address" is returned if the email address returned by Facebook is empty or invalid.
"bad_request"

"apple login prevented" is returned if the user has disabled Apple logins. When this error is returned, an email is sent to the user with a link to enable Apple logins.

POST /api/v1/appleloginfinal

$ curl "https://groups.io/api/v1/appleloginfinal \"
-c "cookies.curl" \
-d code=xxx&state=yyy

Example Successful Response

 {
 "user": 
   {
    "id": 12,
    "object": "user",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "email": "user@example.com",
    "full_name": "",
    "user_name": "",
    "timezone": "",
    "status": "user_status_bounced",
    "profile_photo_url": "",
    "post_pref": "",
    "per_page_pref": "",
    "allow_facebook_login": false,
    "allow_google_login": false,
    "allow_sso_login": false,
    "csrf_token": "",
    "two_factor_enabled": false,
    "recovery_codes": "",
    "dont_munge_message_id": false,
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "time_pref": "",
    "date_pref": "",
    "monday_start": false,
    "profile_privacy": "",
    "default_message_view": "expanded_message_view",
    "topics_sort_dir": "",
    "topic_sort_dir": "",
    "messages_sort_dir": "",
    "expanded_messages_sort_dir": "",
    "search_sort": "",
    "search_sort_dir": "",
    "photos_order_by": "",
    "photos_sort_dir": "",
    "album_order_by": "",
    "album_sort_dir": "",
    "default_calendar_view": "",
    "default_hashtag_view": "",
    "default_rsvp_view": "",
    "home_page": "home_page_calendar",
    "subscriptions": [
      {
       "id": 78,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 81,
       "group_id": 6,
       "group_name": "mygroup",
       "status": "sub_status_banned",
       "post_status": "sub_poststatus_allowed",
       "email_delivery": "email_delivery_digest",
       "message_selection": "message_selection_all",
       "auto_follow_replies": false,
       "max_attachment_size": "max_attachment_size_large",
       "approved_posts": 79,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_app_only",
       "pending_sub_notify": "sub_notify_app_only",
       "sub_notify": "sub_notify_app_only",
       "storage_notify": "sub_notify_app_only",
       "sub_group_notify": "sub_notify_app_only",
       "message_report_notify": "sub_notify_app_only",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "chat_notify": "sub_notify_app_only",
       "photo_notify": "sub_notify_app_only",
       "file_notify": "sub_notify_app_only",
       "wiki_notify": "sub_notify_app_only",
       "database_notify": "sub_notify_app_only",
       "email": "joe@example.com",
       "user_status": "user_status_bounced",
       "user_name": "joe",
       "timezone": "America/Los_Angeles",
       "full_name": "Joe Smith",
       "about_me": "",
       "location": "",
       "website": "https://example.com",
       "profile_photo_url": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "use_signature": false,
       "use_signature_email": false,
       "signature": "",
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "num_drafts": 15,
       "pending_subs": 85,
       "pending_msgs": 11,
       "cover_photo_url": "",
       "icon_url": "",
       "nice_group_name": "",
       "subs_count": 48,
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "perms": 
         {
          "object": "perms",
          "archives_visible": false,
          "polls_visible": false,
          "members_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
          "hashtags_visible": false,
          "guidelines_visible": false,
          "subgroups_visible": false,
          "open_donations_visible": false,
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": false,
          "create_hashtags": false,
          "manage_hashtags": false,
          "manage_integrations": false,
          "manage_group_settings": false,
          "make_moderator": false,
          "manage_member_subscription_options": false,
          "manage_pending_members": false,
          "remove_members": false,
          "ban_members": false,
          "manage_group_billing": false,
          "manage_group_payments": false,
          "edit_archives": false,
          "manage_pending_messages": false,
          "invite_members": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "manage_photos": false,
          "manage_members": false,
          "manage_calendar": false,
          "manage_chats": false,
          "view_member_directory": false,
          "manage_files": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
         },
      }
    ],
   },
 "token": "aabbffed2213234",
}
View Login definition

Example Error Response

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

Google Login Final

Complete the Google login process. If the email address returned by Google matches an existing Groups.io user, then that user is logged in. If it does not match an existing user, a new user is created and logged in.

POST Parameters
state
required
string

Returned from Google.
code
required
string

Returned from Google. Either code or access_token is required. If code is specified, we will exchange it for an access_token.
access_token
required
string

The access token from Google. Either code or access_token is required.
Returns

Returns a login object if a valid code and state are present. In addition, one or more HTTP cookies are set in the response. Returns an error otherwise.

Additional Errors
"bad_request"

"invalid state" is returned if the state parameter is invalid or missing.
"bad_request"

"invalid code" is returned if the code parameter is invalid or missing.
"bad_request"

"inactive user" is returned if the user has been disabled.
"bad_request"

"two factor enabled" is returned if the user has two-factor authentication enabled, which prevents Google logins.
"bad_request"

"invalid email address" is returned if the email address returned by Facebook is empty or invalid.
"bad_request"

"google login prevented" is returned if the user has disabled Google logins. When this error is returned, an email is sent to the user with a link to enable Google logins.

POST /api/v1/googleloginfinal

$ curl "https://groups.io/api/v1/googleloginfinal \"
-c "cookies.curl" \
-d code=xxx&state=yyy

Example Successful Response

 {
 "user": 
   {
    "id": 14,
    "object": "user",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "email": "user@example.com",
    "full_name": "",
    "user_name": "",
    "timezone": "",
    "status": "user_status_bounced",
    "profile_photo_url": "",
    "post_pref": "",
    "per_page_pref": "",
    "allow_facebook_login": false,
    "allow_google_login": false,
    "allow_sso_login": false,
    "csrf_token": "",
    "two_factor_enabled": false,
    "recovery_codes": "",
    "dont_munge_message_id": false,
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "time_pref": "",
    "date_pref": "",
    "monday_start": false,
    "profile_privacy": "",
    "default_message_view": "expanded_message_view",
    "topics_sort_dir": "",
    "topic_sort_dir": "",
    "messages_sort_dir": "",
    "expanded_messages_sort_dir": "",
    "search_sort": "",
    "search_sort_dir": "",
    "photos_order_by": "",
    "photos_sort_dir": "",
    "album_order_by": "",
    "album_sort_dir": "",
    "default_calendar_view": "",
    "default_hashtag_view": "",
    "default_rsvp_view": "",
    "home_page": "home_page_calendar",
    "subscriptions": [
      {
       "id": 93,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 36,
       "group_id": 55,
       "group_name": "mygroup",
       "status": "sub_status_banned",
       "post_status": "sub_poststatus_allowed",
       "email_delivery": "email_delivery_digest",
       "message_selection": "message_selection_all",
       "auto_follow_replies": false,
       "max_attachment_size": "max_attachment_size_large",
       "approved_posts": 60,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_app_only",
       "pending_sub_notify": "sub_notify_app_only",
       "sub_notify": "sub_notify_app_only",
       "storage_notify": "sub_notify_app_only",
       "sub_group_notify": "sub_notify_app_only",
       "message_report_notify": "sub_notify_app_only",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "chat_notify": "sub_notify_app_only",
       "photo_notify": "sub_notify_app_only",
       "file_notify": "sub_notify_app_only",
       "wiki_notify": "sub_notify_app_only",
       "database_notify": "sub_notify_app_only",
       "email": "joe@example.com",
       "user_status": "user_status_bounced",
       "user_name": "joe",
       "timezone": "America/Los_Angeles",
       "full_name": "Joe Smith",
       "about_me": "",
       "location": "",
       "website": "https://example.com",
       "profile_photo_url": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "use_signature": false,
       "use_signature_email": false,
       "signature": "",
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "num_drafts": 36,
       "pending_subs": 6,
       "pending_msgs": 83,
       "cover_photo_url": "",
       "icon_url": "",
       "nice_group_name": "",
       "subs_count": 28,
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "perms": 
         {
          "object": "perms",
          "archives_visible": false,
          "polls_visible": false,
          "members_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
          "hashtags_visible": false,
          "guidelines_visible": false,
          "subgroups_visible": false,
          "open_donations_visible": false,
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": false,
          "create_hashtags": false,
          "manage_hashtags": false,
          "manage_integrations": false,
          "manage_group_settings": false,
          "make_moderator": false,
          "manage_member_subscription_options": false,
          "manage_pending_members": false,
          "remove_members": false,
          "ban_members": false,
          "manage_group_billing": false,
          "manage_group_payments": false,
          "edit_archives": false,
          "manage_pending_messages": false,
          "invite_members": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "manage_photos": false,
          "manage_members": false,
          "manage_calendar": false,
          "manage_chats": false,
          "view_member_directory": false,
          "manage_files": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
         },
      }
    ],
   },
 "token": "aabbffed2213234",
}
View Login definition

Example Error Response

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

Member Notices

Endpoints to manipulate member notices.

New Member Notice

Create a new member notice.

Permissions Needed

You must have the manage_group_settings permission to use this call with a group.

POST Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
csrf
required
string

The csrf_token from the user object returned when first logged in.
name
required
string

Name of this member notice
type
required
string

Type of member notice, can be: member_notice_joining, member_notice_pending, member_notice_leaving, member_notice_banned, member_notice_rejected_sub, member_notice_invite, member_notice_direct_add, member_notice_rejected_message, member_notice_removed_sub, member_notice_post_to_sub, member_notice_guidelines, member_notice_locked_group, member_notice_monthly_reminder
subject
required
string

Subject used when sending emails
message
required
string

The message, in HTML format
guidelines_subject
optional
string

For Guidelines, the subject to use when sending the monthly email
is_default
optional
boolean

Use this message for email commands
send_on_join
optional
boolean

For Guidelines, send to new members at same time as welcome message
send_monthly
optional
boolean

For Guidelines, send monthly to the group members
send_monthly_special
optional
boolean

For Guidelines, send monthly to members on special only
private
optional
boolean

For Guidelines, if the guidelines are public or for members only
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a member notice object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid group_id" is returned if the group id is missing or invalid.
"bad_request"

"invalid name" is returned if the name is missing or invalid.
"bad_request"

"invalid subject" is returned if the subject is missing or invalid.
"bad_request"

"invalid type" is returned if the type is missing or invalid.
"bad_request"

"invalid message" is returned if the message is missing or invalid.
"bad_request"

"already have guidelines" is returned if the message is of type group_message_guidelines and there already is a notice of the same type.

POST /api/v1/newmembernotice

$ curl "https://groups.io/api/v1/newmembernotice" \
-b "cookies.curl" \
-d group_id=12&subject=Test&name=testing&csrf=1234

Example Successful Response

 {
 "id": 1,
 "object": "member_notice",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "group_id": 12,
 "type": "member_notice_banned",
 "name": "",
 "subject": "",
 "message": "",
 "is_default": false,
 "send_monthly": false,
 "send_monthly_special": false,
 "send_on_join": false,
 "private": false,
 "guidelines_monthly_subject": "",
}
View Member Notice definition

Example Error Response

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

Update Member Notice

Update a member notice object.

Permissions Needed

You must have the manage_group_settings permission to use this call with a group.

POST Parameters
member_notice_id
required
number

ID of the member notice to update.
csrf
required
string

The csrf_token from the user object returned when first logged in.
name
optional
string

Name of this member notice
type
optional
string

Type of member notice, can be: member_notice_joining, member_notice_pending, member_notice_leaving, member_notice_banned, member_notice_rejected_sub, member_notice_invite, member_notice_direct_add, member_notice_rejected_message, member_notice_removed_sub, member_notice_post_to_sub, member_notice_guidelines, member_notice_locked_group, member_notice_monthly_reminder
subject
optional
string

Subject used when sending emails
message
optional
string

The message, in HTML format
guidelines_subject
optional
string

For Guidelines, the subject to use when sending the monthly email
is_default
optional
boolean

Use this message for email commands
send_on_join
optional
boolean

For Guidelines, send to new members at same time as welcome message
send_monthly
optional
boolean

For Guidelines, send monthly to the group members
send_monthly_special
optional
boolean

For Guidelines, send monthly to members on special only
private
optional
boolean

For Guidelines, if the guidelines are public or for members only
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns the member-notice object. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.

Additional Errors
"bad_request"

"invalid member_notice_id" is returned if the member_notice id is missing or invalid.
"bad_request"

"already have guidelines" is returned if the message is of type group_message_guidelines and there already is a notice of the same type.

POST /api/v1/updatemembernotice

$ curl "https://groups.io/api/v1/updatemembernotice" \
-b "cookies.curl" \
-d member_notice_id=12&subject=Test&name=testing&csrf=1234

Example Successful Response

 {
 "id": 79,
 "object": "member_notice",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "group_id": 63,
 "type": "member_notice_banned",
 "name": "",
 "subject": "",
 "message": "",
 "is_default": false,
 "send_monthly": false,
 "send_monthly_special": false,
 "send_on_join": false,
 "private": false,
 "guidelines_monthly_subject": "",
}
View Member Notice definition

Example Error Response

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

Delete Member Notice

Delete a member notice object.

Permissions Needed

You must have the manage_group_settings permission to use this call with a group.

POST Parameters
member_notice_id
required
number

ID of the member notice to delete.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns HTTP 200 on success. Returns an error if parameters are invalid (e.g. specifying an invalid group_id). Below are the unique errors to this call.a

Additional Errors
"bad_request"

"invalid member_notice_id" is returned if the member notice id is missing or invalid.

POST /api/v1/deletemembernotice

$ curl "https://groups.io/api/v1/deletemembernotice" \
-b "cookies.curl" \
-d member_notice_id=12&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Get Member Notices

Get member notices. Member notices are returned using the pagination request and object format.

Permissions Needed

You must have the manage_group_settings permission to use this call with a group.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
type
optional
string

Type of member notice to return, can be: member_notice_joining, member_notice_pending, member_notice_leaving, member_notice_banned, member_notice_rejected_sub, member_notice_invite, member_notice_direct_add, member_notice_rejected_message, member_notice_removed_sub, member_notice_post_to_sub, member_notice_guidelines, member_notice_locked_group, member_notice_monthly_reminder
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: name, msgtype, updated, created.
sort_dir
optional
string

Sort direction. Can be asc or desc.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a member notice list object if successful. Returns an error if there is an error.

Additional Errors
No additional errors

GET /api/v1/getmembernotices

$ curl "https://groups.io/api/v1/getmembernotices?group_id=12" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 43,
 "start_item": 87,
 "end_item": 32,
 "has_more": false,
 "next_page_token": 23,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 23,
    "object": "member_notice",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 25,
    "type": "member_notice_banned",
    "name": "",
    "subject": "",
    "message": "",
    "is_default": false,
    "send_monthly": false,
    "send_monthly_special": false,
    "send_on_join": false,
    "private": false,
    "guidelines_monthly_subject": "",
   }
 ],
}
View Member Notice List definition

Example Error Response

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

Members

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. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
member_info_id
required
number

ID of the member info object.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a member info 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.

POST /api/v1/approvemember

$ curl "https://groups.io/api/v1/approvemember" \
-b "cookies.curl" \
-d group_id=1 \
-d member_info_id=2 \
-d csrf=12345

Example Successful Response

 {
 "id": 90,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 77,
 "group_id": 1,
 "group_name": "mygroup",
 "status": "sub_status_banned",
 "post_status": "sub_poststatus_allowed",
 "email_delivery": "email_delivery_digest",
 "message_selection": "message_selection_all",
 "auto_follow_replies": false,
 "max_attachment_size": "max_attachment_size_large",
 "approved_posts": 1,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_app_only",
 "pending_sub_notify": "sub_notify_app_only",
 "sub_notify": "sub_notify_app_only",
 "storage_notify": "sub_notify_app_only",
 "sub_group_notify": "sub_notify_app_only",
 "message_report_notify": "sub_notify_app_only",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "chat_notify": "sub_notify_app_only",
 "photo_notify": "sub_notify_app_only",
 "file_notify": "sub_notify_app_only",
 "wiki_notify": "sub_notify_app_only",
 "database_notify": "sub_notify_app_only",
 "email": "joe@example.com",
 "user_status": "user_status_bounced",
 "user_name": "joe",
 "timezone": "America/Los_Angeles",
 "full_name": "Joe Smith",
 "about_me": "",
 "location": "",
 "website": "https://example.com",
 "profile_photo_url": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "use_signature": false,
 "use_signature_email": false,
 "signature": "",
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "num_drafts": 47,
 "pending_subs": 8,
 "pending_msgs": 7,
 "cover_photo_url": "",
 "icon_url": "",
 "nice_group_name": "",
 "subs_count": 59,
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
}
View Member Info definition

Example Error Response

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

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. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
member_info_id
required
number

ID of the member info object.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a member info 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

POST /api/v1/banmember

$ curl "https://groups.io/api/v1/banmember" \
-b "cookies.curl" \
-d group_id=1 \
-d member_info_id=2 \
-d csrf=12345

Example Successful Response

 {
 "id": 14,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 96,
 "group_id": 52,
 "group_name": "mygroup",
 "status": "sub_status_banned",
 "post_status": "sub_poststatus_allowed",
 "email_delivery": "email_delivery_digest",
 "message_selection": "message_selection_all",
 "auto_follow_replies": false,
 "max_attachment_size": "max_attachment_size_large",
 "approved_posts": 64,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_app_only",
 "pending_sub_notify": "sub_notify_app_only",
 "sub_notify": "sub_notify_app_only",
 "storage_notify": "sub_notify_app_only",
 "sub_group_notify": "sub_notify_app_only",
 "message_report_notify": "sub_notify_app_only",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "chat_notify": "sub_notify_app_only",
 "photo_notify": "sub_notify_app_only",
 "file_notify": "sub_notify_app_only",
 "wiki_notify": "sub_notify_app_only",
 "database_notify": "sub_notify_app_only",
 "email": "joe@example.com",
 "user_status": "user_status_bounced",
 "user_name": "joe",
 "timezone": "America/Los_Angeles",
 "full_name": "Joe Smith",
 "about_me": "",
 "location": "",
 "website": "https://example.com",
 "profile_photo_url": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "use_signature": false,
 "use_signature_email": false,
 "signature": "",
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "num_drafts": 88,
 "pending_subs": 37,
 "pending_msgs": 0,
 "cover_photo_url": "",
 "icon_url": "",
 "nice_group_name": "",
 "subs_count": 92,
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
}
View Member Info definition

Example Error Response

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

Bulk Remove Members

Remove one or more members 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. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
emails
required
string

A newline separated list of email addresses to remove.
csrf
required
string

The csrf_token from the user object returned when first logged in.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a bulk remove results object if the bulk remove 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
  • If a removed member's status is sub_status_pending, the active Rejected Subscription member notice will be sent to the member, if there is one.
  • If a removed member's status is sub_status_normal, the active Removed Member notice will be sent to the member, if there is one.
  • If a removed member's status is sub_status_banned, no member notices will be sent out.

POST /api/v1/bulkremovemembers

$ curl "https://groups.io/api/v1/bulkremovemembers" \
-b "cookies.curl" \
-d group_id=1 \
-d $'emails=test@example.com\njohn@smith.com` \
-d csrf=12345

TODO: FIX

Example Successful Response

 {
 "id": 38,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 95,
 "group_id": 97,
 "group_name": "mygroup",
 "status": "sub_status_banned",
 "post_status": "sub_poststatus_allowed",
 "email_delivery": "email_delivery_digest",
 "message_selection": "message_selection_all",
 "auto_follow_replies": false,
 "max_attachment_size": "max_attachment_size_large",
 "approved_posts": 44,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_app_only",
 "pending_sub_notify": "sub_notify_app_only",
 "sub_notify": "sub_notify_app_only",
 "storage_notify": "sub_notify_app_only",
 "sub_group_notify": "sub_notify_app_only",
 "message_report_notify": "sub_notify_app_only",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "chat_notify": "sub_notify_app_only",
 "photo_notify": "sub_notify_app_only",
 "file_notify": "sub_notify_app_only",
 "wiki_notify": "sub_notify_app_only",
 "database_notify": "sub_notify_app_only",
 "email": "joe@example.com",
 "user_status": "user_status_bounced",
 "user_name": "joe",
 "timezone": "America/Los_Angeles",
 "full_name": "Joe Smith",
 "about_me": "",
 "location": "",
 "website": "https://example.com",
 "profile_photo_url": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "use_signature": false,
 "use_signature_email": false,
 "signature": "",
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "num_drafts": 78,
 "pending_subs": 8,
 "pending_msgs": 27,
 "cover_photo_url": "",
 "icon_url": "",
 "nice_group_name": "",
 "subs_count": 63,
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
}
View Member Info definition

Example Error Response

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

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. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
emails
required
string

A newline separated list of email addresses to add.
csrf
string

The csrf_token from the user object returned when first logged in.
subject
optional
string

Subject line to use for the direct add notification sent to users.
message
optional
string

Message to include with the direct add notification sent to users.
subgroupids
optional
string

A comma separated list of IDs of sub groups to also add these people to.
subgroupnames
optional
string

A comma separated list of names of sub groups to also add these people to.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
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

"trial group" is returned if the group is a trial 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
  • For premium groups, 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. There is no daily limit for Enterprise groups.
  • If a subgroupid or subgroupname is specified that is actually a group alias, the pointed-to group will be used instead.

POST /api/v1/directadd

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

Example Successful Response

 {
 "object": "direct_add_results",
 "total_emails": 54,
 "errors": [
   {
    "object": "direct_add_error",
    "email": "",
    "status": "",
    "group_id": 52,
   }
 ],
 "added_members": [
   {
    "id": 11,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 1,
    "group_id": 38,
    "group_name": "mygroup",
    "status": "sub_status_banned",
    "post_status": "sub_poststatus_allowed",
    "email_delivery": "email_delivery_digest",
    "message_selection": "message_selection_all",
    "auto_follow_replies": false,
    "max_attachment_size": "max_attachment_size_large",
    "approved_posts": 72,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_app_only",
    "pending_sub_notify": "sub_notify_app_only",
    "sub_notify": "sub_notify_app_only",
    "storage_notify": "sub_notify_app_only",
    "sub_group_notify": "sub_notify_app_only",
    "message_report_notify": "sub_notify_app_only",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "chat_notify": "sub_notify_app_only",
    "photo_notify": "sub_notify_app_only",
    "file_notify": "sub_notify_app_only",
    "wiki_notify": "sub_notify_app_only",
    "database_notify": "sub_notify_app_only",
    "email": "joe@example.com",
    "user_status": "user_status_bounced",
    "user_name": "joe",
    "timezone": "America/Los_Angeles",
    "full_name": "Joe Smith",
    "about_me": "",
    "location": "",
    "website": "https://example.com",
    "profile_photo_url": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "use_signature": false,
    "use_signature_email": false,
    "signature": "",
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "num_drafts": 88,
    "pending_subs": 80,
    "pending_msgs": 41,
    "cover_photo_url": "",
    "icon_url": "",
    "nice_group_name": "",
    "subs_count": 71,
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
   }
 ],
}
View Direct Add Results definition

Example Error Response

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

Get Member

Get a member of a group. A member is represented by a member info object.

Permissions Needed

You must have the members_visible permission to use this call.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
member_info_id
required
number

ID of the member info object
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

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

Additional Errors
No additional errors

GET /api/v1/getmember

$ curl "https://groups.io/api/v1/getmember?group_id=2&member_info_id=46" \
-b "cookies.curl"

Example Successful Response

 {
 "id": 41,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 14,
 "group_id": 27,
 "group_name": "mygroup",
 "status": "sub_status_banned",
 "post_status": "sub_poststatus_allowed",
 "email_delivery": "email_delivery_digest",
 "message_selection": "message_selection_all",
 "auto_follow_replies": false,
 "max_attachment_size": "max_attachment_size_large",
 "approved_posts": 36,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_app_only",
 "pending_sub_notify": "sub_notify_app_only",
 "sub_notify": "sub_notify_app_only",
 "storage_notify": "sub_notify_app_only",
 "sub_group_notify": "sub_notify_app_only",
 "message_report_notify": "sub_notify_app_only",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "chat_notify": "sub_notify_app_only",
 "photo_notify": "sub_notify_app_only",
 "file_notify": "sub_notify_app_only",
 "wiki_notify": "sub_notify_app_only",
 "database_notify": "sub_notify_app_only",
 "email": "joe@example.com",
 "user_status": "user_status_bounced",
 "user_name": "joe",
 "timezone": "America/Los_Angeles",
 "full_name": "Joe Smith",
 "about_me": "",
 "location": "",
 "website": "https://example.com",
 "profile_photo_url": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "use_signature": false,
 "use_signature_email": false,
 "signature": "",
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "num_drafts": 38,
 "pending_subs": 84,
 "pending_msgs": 44,
 "cover_photo_url": "",
 "icon_url": "",
 "nice_group_name": "",
 "subs_count": 37,
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "perms": 
   {
    "object": "perms",
    "archives_visible": false,
    "polls_visible": false,
    "members_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
    "hashtags_visible": false,
    "guidelines_visible": false,
    "subgroups_visible": false,
    "open_donations_visible": false,
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": false,
    "create_hashtags": false,
    "manage_hashtags": false,
    "manage_integrations": false,
    "manage_group_settings": false,
    "make_moderator": false,
    "manage_member_subscription_options": false,
    "manage_pending_members": false,
    "remove_members": false,
    "ban_members": false,
    "manage_group_billing": false,
    "manage_group_payments": false,
    "edit_archives": false,
    "manage_pending_messages": false,
    "invite_members": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "manage_photos": false,
    "manage_members": false,
    "manage_calendar": false,
    "manage_chats": false,
    "view_member_directory": false,
    "manage_files": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
   },
}
View Member Info definition

Example Error Response

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

Get Member Directory

Get the group member directory. Each member is represented by a member info object. Member info objects are returned using the pagination request and object format.

Permissions Needed

You must have the view_member_directory permission to use this call.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
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.
sort_dir
optional
string

Sort direction. Can be 'asc' or 'desc'.
extended
optional
boolean

If true, the endpoint will return additional information. See Extended Return Information for more information.
Returns

Returns a member info list object if successful. 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"

"private profile" is returned the user's profile is private. Only people without a private profile can view the member directory.
  • No additional errors

GET /api/v1/getmemberdirectory

$ curl "https://groups.io/api/v1/getmemberdirectory?group_id=7" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 98,
 "start_item": 23,
 "end_item": 94,
 "has_more": false,
 "next_page_token": 95,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 62,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 35,
    "group_id": 79,
    "group_name": "mygroup",
    "status": "sub_status_banned",
    "post_status": "sub_poststatus_allowed",
    "email_delivery": "email_delivery_digest",
    "message_selection": "message_selection_all",
    "auto_follow_replies": false,
    "max_attachment_size": "max_attachment_size_large",
    "approved_posts": 7,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_app_only",
    "pending_sub_notify": "sub_notify_app_only",
    "sub_notify": "sub_notify_app_only",
    "storage_notify": "sub_notify_app_only",
    "sub_group_notify": "sub_notify_app_only",
    "message_report_notify": "sub_notify_app_only",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "chat_notify": "sub_notify_app_only",
    "photo_notify": "sub_notify_app_only",
    "file_notify": "sub_notify_app_only",
    "wiki_notify": "sub_notify_app_only",
    "database_notify": "sub_notify_app_only",
    "email": "joe@example.com",
    "user_status": "user_status_bounced",
    "user_name": "joe",
    "timezone": "America/Los_Angeles",
    "full_name": "Joe Smith",
    "about_me": "",
    "location": "",
    "website": "https://example.com",
    "profile_photo_url": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "use_signature": false,
    "use_signature_email": false,
    "signature": "",
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "num_drafts": 28,
    "pending_subs": 82,
    "pending_msgs": 95,
    "cover_photo_url": "",
    "icon_url": "",
    "nice_group_name": "",
    "subs_count": 56,
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "perms": 
      {
       "object": "perms",
       "archives_visible": false,
       "polls_visible": false,
       "members_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
       "hashtags_visible": false,
       "guidelines_visible": false,
       "subgroups_visible": false,
       "open_donations_visible": false,
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": false,
       "create_hashtags": false,
       "manage_hashtags": false,
       "manage_integrations": false,
       "manage_group_settings": false,
       "make_moderator": false,
       "manage_member_subscription_options": false,
       "manage_pending_members": false,
       "remove_members": false,
       "ban_members": false,
       "manage_group_billing": false,
       "manage_group_payments": false,
       "edit_archives": false,
       "manage_pending_messages": false,
       "invite_members": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "manage_photos": false,
       "manage_members": false,
       "manage_calendar": false,
       "manage_chats": false,
       "view_member_directory": false,
       "manage_files": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
      },
   }
 ],
}
View Member Info List definition

Example Error Response

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

Get Members

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

Permissions Needed

You must have the members_visible or view_member_directory permission to use this call.

Query Parameters
group_id
required
number

ID of the group. Either group_id or group_name must be specified.
group_name
required
string

Name of the group. Either group_id or group_name must be specified.
type
optional
default is members

The type of member to be returned, can be pending, banned, mods, members, bouncing. 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'.