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": ""
    }

Libraries

The following are unofficial libraries.

JAVA

github.com/lake54/groupsio-api-java

Authentication

Authentication

Authentication to the API is performed via HTTP cookies, using cookies set from the login API call.

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

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
number

If 1, then extended information is also returned with the call.
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": 81,
 "start_item": 87,
 "end_item": 47,
 "has_more": false,
 "next_page_token": 59,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "group_perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
 "group": 
   {
    "id": 81,
    "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,
    "moderated": false,
    "new_users_moderated": false,
    "unmoderate_users_after": 18,
    "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,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 25,
    "org_id": 40,
    "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": 56,
    "max_number_of_reposts": 0,
    "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": 94,
    "auto_moderate_threads": false,
    "moderate_threads_after": 11,
    "subgroupcategoryid": 62,
    "subs_count": 89,
    "pending_subs_count": 28,
    "pending_msgs_count": 74,
    "open_chats_count": 11,
    "threads_count": 45,
    "messages_count": 37,
    "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_monthly",
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   },
 "sub_data": [
   {
    "id": 6,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 95,
    "group_id": 66,
    "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": 28,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 58,
    "pending_subs": 47,
    "pending_msgs": 47,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
 "data": [
   {
    "id": 87,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 88,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 90,
    "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": 15,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 41,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hash_tag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 8,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}
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
number

If 1, then extended information is also returned with the call.
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": 87,
 "start_item": 31,
 "end_item": 29,
 "has_more": false,
 "next_page_token": 56,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "group_perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
 "group": 
   {
    "id": 37,
    "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,
    "moderated": false,
    "new_users_moderated": false,
    "unmoderate_users_after": 31,
    "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,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 85,
    "org_id": 26,
    "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": 13,
    "max_number_of_reposts": 90,
    "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": 94,
    "auto_moderate_threads": false,
    "moderate_threads_after": 63,
    "subgroupcategoryid": 33,
    "subs_count": 47,
    "pending_subs_count": 78,
    "pending_msgs_count": 24,
    "open_chats_count": 59,
    "threads_count": 53,
    "messages_count": 57,
    "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_monthly",
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   },
 "cover_photo_url": "",
 "sub_data": [
   {
    "id": 21,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 89,
    "group_id": 99,
    "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": 0,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 5,
    "pending_subs": 88,
    "pending_msgs": 38,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
 "topic": 
   {
    "id": 3,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 55,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 51,
    "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": 10,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 5,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hash_tag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 56,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   },
 "data": [
   {
    "id": 66,
    "object": "message",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 28,
    "group_id": 61,
    "topic_id": 2,
    "body": "",
    "quoted": "",
    "remainder": "",
    "snippet": "",
    "subject": "",
    "name": "",
    "profile_photo_url": "",
    "is_plain_text": false,
    "msg_num": 83,
    "has_liked": false,
    "num_likes": 46,
    "is_closed": false,
    "is_moderated": false,
    "reply_to": "group_reply_only_to_sender",
    "can_repost": false,
    "hashtags": [
      {
       "id": 63,
       "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": "hash_tag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 2,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}
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.

GET /api/v1/getmessages

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

Example Successful Response

 {
 "object": "list",
 "total_count": 18,
 "start_item": 47,
 "end_item": 94,
 "has_more": false,
 "next_page_token": 77,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "group_perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
 "group": 
   {
    "id": 63,
    "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,
    "moderated": false,
    "new_users_moderated": false,
    "unmoderate_users_after": 96,
    "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,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 20,
    "org_id": 23,
    "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": 53,
    "max_number_of_reposts": 37,
    "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": 33,
    "auto_moderate_threads": false,
    "moderate_threads_after": 41,
    "subgroupcategoryid": 59,
    "subs_count": 33,
    "pending_subs_count": 43,
    "pending_msgs_count": 91,
    "open_chats_count": 2,
    "threads_count": 78,
    "messages_count": 36,
    "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_monthly",
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   },
 "cover_photo_url": "",
 "sub_data": [
   {
    "id": 46,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 7,
    "group_id": 40,
    "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": 3,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 52,
    "pending_subs": 43,
    "pending_msgs": 5,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
 "topic": 
   {
    "id": 98,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 25,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 51,
    "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": 15,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 57,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hash_tag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 87,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   },
 "data": [
   {
    "id": 10,
    "object": "message",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 10,
    "group_id": 85,
    "topic_id": 90,
    "body": "",
    "quoted": "",
    "remainder": "",
    "snippet": "",
    "subject": "",
    "name": "",
    "profile_photo_url": "",
    "is_plain_text": false,
    "msg_num": 32,
    "has_liked": false,
    "num_likes": 98,
    "is_closed": false,
    "is_moderated": false,
    "reply_to": "group_reply_only_to_sender",
    "can_repost": false,
    "hashtags": [
      {
       "id": 53,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 91,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hash_tag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 82,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}
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.
Returns

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

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.

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 .

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": 84,
 "start_item": 97,
 "end_item": 67,
 "has_more": false,
 "next_page_token": 37,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "group_id": 71,
 "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": 94,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 26,
    "name": "",
    "alias": 
      {
      },
    "mods_only_post": false,
    "mods_only_replies": false,
    "no_email": false,
    "moderated": false,
    "special": false,
    "replies_unmoderated": false,
    "locked": false,
    "until": "hash_tag_delete_day",
    "close_instead_of_delete": false,
    "description": "",
    "color_name": "tag_antique_pink",
    "color_hex": "",
    "reply_to": "thread_reply_group_default",
    "topic_count": 2,
    "last_message_date": "2009-11-10T15:00:00-08:00",
   },
 "poster_user_id": 81,
 "poster_profile_photo_url": "",
 "poster_name": "",
 "can_view_poster_profile": false,
 "data": [
   {
    "id": 79,
    "object": "search_result",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 66,
    "topic_id": 70,
    "summary": "",
    "subject": "",
    "user_id": 93,
    "profile_photo_url": "",
    "name": "",
    "can_view_profile": false,
    "rev_count": 86,
    "msg_num": 19,
    "num_msgs_in_topic": 81,
    "is_closed": false,
    "is_moderated": false,
    "is_sticky": false,
    "has_attachments": false,
    "hashtags": [
      {
       "id": 52,
       "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": "hash_tag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 85,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}
View Search Results List 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": 10,
 "object": "chat",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 87,
 "profile_photo_url": "",
 "name": "",
 "can_view_profile": false,
 "group_id": 49,
 "subject": "The chat subject",
 "desc": "This is the description of the chat",
 "is_closed": false,
 "num_messages": 28,
 "chat_sub": 
   {
    "id": 18,
    "object": "chat_sub",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 84,
    "group_id": 3,
    "chat_id": 24,
    "last_msg_seen": 47,
   },
}
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": 12,
 "object": "chat",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 32,
 "profile_photo_url": "",
 "name": "",
 "can_view_profile": false,
 "group_id": 16,
 "subject": "The chat subject",
 "desc": "This is the description of the chat",
 "is_closed": false,
 "num_messages": 39,
 "chat_sub": 
   {
    "id": 40,
    "object": "chat_sub",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 86,
    "group_id": 51,
    "chat_id": 76,
    "last_msg_seen": 40,
   },
}
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 view_chats 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": 51,
 "start_item": 44,
 "end_item": 64,
 "has_more": false,
 "next_page_token": 5,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 83,
    "object": "chat",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 1,
    "profile_photo_url": "",
    "name": "",
    "can_view_profile": false,
    "group_id": 90,
    "subject": "The chat subject",
    "desc": "This is the description of the chat",
    "is_closed": false,
    "num_messages": 2,
    "chat_sub": 
      {
       "id": 58,
       "object": "chat_sub",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 67,
       "group_id": 31,
       "chat_id": 78,
       "last_msg_seen": 54,
      },
   }
 ],
}
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.a

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 view_chats 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": 22,
 "object": "chat_sub",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 23,
 "group_id": 42,
 "chat_id": 8,
 "last_msg_seen": 43,
}
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": 68,
 "start_item": 66,
 "end_item": 10,
 "has_more": false,
 "next_page_token": 35,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 40,
    "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": 57,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 71,
    "pending_msgs": 39,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
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.a

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": 30,
 "start_item": 13,
 "end_item": 0,
 "has_more": false,
 "next_page_token": 59,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 20,
    "object": "chat_message",
    "created": "2009-11-10T15:00:00-08:00",
    "version": 83,
    "user_id": 70,
    "group_id": 84,
    "chat_id": 47,
    "type": "chat_msg_type_closed",
    "message": "",
    "msg_num": 10,
    "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": ""
 }

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 and draft_type_reply 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.
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.

POST /api/v1/newdraft

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

Example Successful Response

 {
 "id": 65,
 "object": "draft",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 62,
 "group_id": 29,
 "draft_type": "",
 "subject": "",
 "body": "",
 "body_type": "",
 "is_special": false,
 "num_attachments": 20,
 "next_attachment_id": 48,
 "message_id": 56,
 "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).
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": 95,
 "object": "draft",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 66,
 "group_id": 0,
 "draft_type": "",
 "subject": "",
 "body": "",
 "body_type": "",
 "is_special": false,
 "num_attachments": 56,
 "next_attachment_id": 29,
 "message_id": 92,
 "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.
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": 31,
 "start_item": 77,
 "end_item": 86,
 "has_more": false,
 "next_page_token": 20,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 99,
    "object": "draft",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 62,
    "group_id": 47,
    "draft_type": "",
    "subject": "",
    "body": "",
    "body_type": "",
    "is_special": false,
    "num_attachments": 92,
    "next_attachment_id": 88,
    "message_id": 11,
    "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.
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.
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": 3,
 "start_item": 88,
 "end_item": 18,
 "has_more": false,
 "next_page_token": 56,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 19,
    "object": "draft_attachment",
    "draft_id": 7,
    "url": "",
    "filename": "",
    "size": 57,
    "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.
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": 52,
 "start_item": 75,
 "end_item": 81,
 "has_more": false,
 "next_page_token": 53,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 95,
    "object": "draft_attachment",
    "draft_id": 17,
    "url": "",
    "filename": "",
    "size": 93,
    "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.
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.
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"

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

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.

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": 70,
 "object": "event",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "creator_name": "@JohnSmith",
 "group_id": 96,
 "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": 86,
 "additional_guests": false,
 "comment_label": "",
 "yes_message": "",
 "has_rsvp": false,
 "rsvp_type": "",
 "rsvp_comment": "",
 "rsvp_additional_guests": 32,
}
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.

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": 20,
 "start_item": 60,
 "end_item": 22,
 "has_more": false,
 "next_page_token": 29,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 61,
    "object": "event",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "creator_name": "@JohnSmith",
    "group_id": 60,
    "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": 20,
    "additional_guests": false,
    "comment_label": "",
    "yes_message": "",
    "has_rsvp": false,
    "rsvp_type": "",
    "rsvp_comment": "",
    "rsvp_additional_guests": 79,
   }
 ],
}
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.
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": 54,
 "object": "rsvp",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "event_id": 64,
 "group_id": 60,
 "user_id": 51,
 "user_name": "",
 "full_name": "",
 "email": "",
 "profile_photo_url": "",
 "type": "rsvp_maybe",
 "comment": "",
 "additional_guests": 81,
}
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

GET /api/v1/feed

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

Example Successful Response

 {
 "object": "list",
 "total_count": 57,
 "start_item": 16,
 "end_item": 0,
 "has_more": false,
 "next_page_token": 39,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "object": "feed",
    "member_info": 
      {
       "id": 37,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 33,
       "group_id": 61,
       "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": 4,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_email",
       "pending_sub_notify": "sub_notify_email",
       "sub_notify": "sub_notify_email",
       "storage_notify": "sub_notify_email",
       "sub_group_notify": "sub_notify_email",
       "message_report_notify": "sub_notify_email",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "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": 85,
       "pending_subs": 9,
       "pending_msgs": 15,
       "perms": 
         {
          "object": "perms",
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": 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,
          "view_databases": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "view_photos": false,
          "manage_photos": false,
          "manage_members": false,
          "view_calendar": false,
          "manage_calendar": false,
          "view_chats": false,
          "manage_chats": false,
          "view_member_directory": false,
          "view_files": false,
          "manage_files": false,
          "view_members": false,
          "view_wiki": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_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,
         },
      },
    "group": 
      {
       "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,
       "moderated": false,
       "new_users_moderated": false,
       "unmoderate_users_after": 14,
       "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,
       "has_cover_photo": false,
       "has_icon": false,
       "parent_group_id": 40,
       "org_id": 62,
       "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": 40,
       "max_number_of_reposts": 0,
       "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": 84,
       "auto_moderate_threads": false,
       "moderate_threads_after": 73,
       "subgroupcategoryid": 35,
       "subs_count": 43,
       "pending_subs_count": 21,
       "pending_msgs_count": 90,
       "open_chats_count": 74,
       "threads_count": 69,
       "messages_count": 70,
       "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_monthly",
       "perms": 
         {
          "object": "perms",
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": 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,
          "view_databases": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "view_photos": false,
          "manage_photos": false,
          "manage_members": false,
          "view_calendar": false,
          "manage_calendar": false,
          "view_chats": false,
          "manage_chats": false,
          "view_member_directory": false,
          "view_files": false,
          "manage_files": false,
          "view_members": false,
          "view_wiki": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_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,
         },
      },
    "topics": [
      {
       "topic": 
         {
          "id": 36,
          "object": "topic",
          "created": "2009-11-10T15:00:00-08:00",
          "updated": "2009-11-10T15:00:00-08:00",
          "group_id": 38,
          "group_subject_tag": "",
          "subject": "",
          "summary": "",
          "name": "",
          "profile_photo_url": "",
          "num_messages": 72,
          "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": 44,
             "object": "hashtag",
             "created": "2009-11-10T15:00:00-08:00",
             "group_id": 95,
             "name": "",
             "alias": 
               {
               },
             "mods_only_post": false,
             "mods_only_replies": false,
             "no_email": false,
             "moderated": false,
             "special": false,
             "replies_unmoderated": false,
             "locked": false,
             "until": "hash_tag_delete_day",
             "close_instead_of_delete": false,
             "description": "",
             "color_name": "tag_antique_pink",
             "color_hex": "",
             "reply_to": "thread_reply_group_default",
             "topic_count": 74,
             "last_message_date": "2009-11-10T15:00:00-08:00",
            }
          ],
         },
       "images": [
         {
          "id": "",
          "object": "attachment",
          "created": "2009-11-10T15:00:00-08:00",
          "group_id": 37,
          "user_id": 24,
          "thread_id": 93,
          "message_num": 6,
          "attach_num": 48,
          "type": "",
          "sub_type": "",
          "name": "",
          "content": "",
          "image_width": 52,
          "image_height": 20,
          "thumbnail_url": "",
         }
       ],
      }
    ],
    "events": [
      {
       "id": 22,
       "object": "event",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "creator_name": "@JohnSmith",
       "group_id": 71,
       "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": 17,
       "additional_guests": false,
       "comment_label": "",
       "yes_message": "",
       "has_rsvp": false,
       "rsvp_type": "",
       "rsvp_comment": "",
       "rsvp_additional_guests": 51,
      }
    ],
    "files": [
      {
       "id": 65,
       "object": "file",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 82,
       "group_id": 79,
       "name": "",
       "desc": "",
       "size": 92,
       "path": "",
       "parent_folder_id": 29,
       "is_folder": false,
       "count": 31,
       "media_type": "",
       "download_url": "",
       "display_name": "",
       "user_name": "",
       "profile_photo_url": "",
       "profile_privacy": "",
       "email": "",
      }
    ],
    "photos": [
      {
       "id": 21,
       "object": "photo",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 55,
       "group_id": 11,
       "name": "",
       "desc": "",
       "media_type": "image/jpeg",
       "size": 43,
       "attachment_num": 53,
       "width": 66,
       "height": 59,
       "album_id": 67,
       "display_name": "",
       "user_name": "",
       "profile_photo_url": "",
       "profile_privacy": "",
       "email": "",
       "format": "gif",
       "focal_length": 3.2,
       "iso": 8,
       "aperture": 3.2,
       "shutter_speed": 8,
       "taken": 28,
       "make": "",
       "model": "",
       "thumbnail_url": "",
       "download_url": "",
      }
    ],
    "chats": [
      {
       "id": 53,
       "object": "chat",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 74,
       "profile_photo_url": "",
       "name": "",
       "can_view_profile": false,
       "group_id": 84,
       "subject": "The chat subject",
       "desc": "This is the description of the chat",
       "is_closed": false,
       "num_messages": 75,
       "chat_sub": 
         {
          "id": 74,
          "object": "chat_sub",
          "created": "2009-11-10T15:00:00-08:00",
          "updated": "2009-11-10T15:00:00-08:00",
          "user_id": 6,
          "group_id": 37,
          "chat_id": 86,
          "last_msg_seen": 67,
         },
      }
    ],
    "wikis": [
      {
       "id": 14,
       "object": "wiki",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 58,
       "group_id": 59,
       "title": "",
       "desc": "",
       "format": "",
       "locked": false,
       "rev_count": 46,
      }
    ],
    "subgroups": [
      {
       "id": 23,
       "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,
       "moderated": false,
       "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,
       "has_cover_photo": false,
       "has_icon": false,
       "parent_group_id": 87,
       "org_id": 57,
       "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": 39,
       "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": 31,
       "auto_moderate_threads": false,
       "moderate_threads_after": 46,
       "subgroupcategoryid": 83,
       "subs_count": 28,
       "pending_subs_count": 16,
       "pending_msgs_count": 26,
       "open_chats_count": 77,
       "threads_count": 12,
       "messages_count": 36,
       "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_monthly",
       "perms": 
         {
          "object": "perms",
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": 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,
          "view_databases": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "view_photos": false,
          "manage_photos": false,
          "manage_members": false,
          "view_calendar": false,
          "manage_calendar": false,
          "view_chats": false,
          "manage_chats": false,
          "view_member_directory": false,
          "view_files": false,
          "manage_files": false,
          "view_members": false,
          "view_wiki": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_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,
         },
      }
    ],
    "tables": [
      {
       "id": 51,
       "object": "databasetable",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "group_id": 5,
       "user_id": 62,
       "name": "",
       "short_desc": "",
       "desc": "",
       "desc_type": "",
       "edit_table": "",
       "edit_rows": "",
       "add_rows": "",
       "view_table": "",
       "num_rows": 89,
       "max_row_id": 98,
       "num_columns": 87,
       "max_col_id": 30,
       "display_template": "",
       "columns": [
         {
          "id": 9,
          "name": "",
          "type": "",
          "required": false,
          "color": "",
          "choices": [""],
          "width": 28,
         }
       ],
      }
    ],
    "hashtags": [
      {
       "id": 59,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 61,
       "name": "",
       "alias": 
         {
         },
       "mods_only_post": false,
       "mods_only_replies": false,
       "no_email": false,
       "moderated": false,
       "special": false,
       "replies_unmoderated": false,
       "locked": false,
       "until": "hash_tag_delete_day",
       "close_instead_of_delete": false,
       "description": "",
       "color_name": "tag_antique_pink",
       "color_hex": "",
       "reply_to": "thread_reply_group_default",
       "topic_count": 2,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}
View Feed List 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 view_files 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.
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": 18,
 "start_item": 45,
 "end_item": 71,
 "has_more": false,
 "next_page_token": 53,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "path": "",
 "files_percentage": 40,
 "files_gigs": "",
 "data": [
   {
    "id": 20,
    "object": "file",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 81,
    "group_id": 5,
    "name": "",
    "desc": "",
    "size": 76,
    "path": "",
    "parent_folder_id": 9,
    "is_folder": false,
    "count": 66,
    "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 view_files 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.
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": 56,
 "object": "file",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 95,
 "group_id": 80,
 "name": "",
 "desc": "",
 "size": 34,
 "path": "",
 "parent_folder_id": 77,
 "is_folder": false,
 "count": 67,
 "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 view_files 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.
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": 78,
 "start_item": 75,
 "end_item": 93,
 "has_more": false,
 "next_page_token": 80,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "path": "",
 "files_percentage": 8,
 "files_gigs": "",
 "data": [
   {
    "id": 31,
    "object": "file",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 65,
    "group_id": 58,
    "name": "",
    "desc": "",
    "size": 84,
    "path": "",
    "parent_folder_id": 42,
    "is_folder": false,
    "count": 23,
    "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.

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": 62,
 "start_item": 73,
 "end_item": 72,
 "has_more": false,
 "next_page_token": 53,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "path": "",
 "files_percentage": 58,
 "files_gigs": "",
 "data": [
   {
    "id": 27,
    "object": "file",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 96,
    "group_id": 48,
    "name": "",
    "desc": "",
    "size": 13,
    "path": "",
    "parent_folder_id": 31,
    "is_folder": false,
    "count": 74,
    "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
sub_group_access
required
string

Who can create subgroups, one of sub_group_subs, sub_group_moderators, sub_group_owners
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
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": 6,
 "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,
 "moderated": false,
 "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,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 31,
 "org_id": 32,
 "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": 77,
 "max_number_of_reposts": 2,
 "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": 54,
 "auto_moderate_threads": false,
 "moderate_threads_after": 83,
 "subgroupcategoryid": 30,
 "subs_count": 86,
 "pending_subs_count": 87,
 "pending_msgs_count": 62,
 "open_chats_count": 4,
 "threads_count": 21,
 "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_monthly",
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
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
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.
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": 98,
 "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,
 "moderated": false,
 "new_users_moderated": false,
 "unmoderate_users_after": 56,
 "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,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 65,
 "org_id": 22,
 "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": 45,
 "max_number_of_reposts": 94,
 "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": 6,
 "auto_moderate_threads": false,
 "moderate_threads_after": 99,
 "subgroupcategoryid": 24,
 "subs_count": 20,
 "pending_subs_count": 44,
 "pending_msgs_count": 59,
 "open_chats_count": 7,
 "threads_count": 24,
 "messages_count": 57,
 "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_monthly",
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
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.

GET /api/v1/getgroup

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

Example Successful Response

 {
 "id": 53,
 "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,
 "moderated": false,
 "new_users_moderated": false,
 "unmoderate_users_after": 74,
 "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,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 75,
 "org_id": 40,
 "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": 89,
 "max_number_of_reposts": 14,
 "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": 45,
 "auto_moderate_threads": false,
 "moderate_threads_after": 39,
 "subgroupcategoryid": 81,
 "subs_count": 31,
 "pending_subs_count": 51,
 "pending_msgs_count": 85,
 "open_chats_count": 29,
 "threads_count": 3,
 "messages_count": 95,
 "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_monthly",
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
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 .

GET /api/v1/getsubgroups

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

Example Successful Response

 {
 "object": "list",
 "total_count": 92,
 "start_item": 72,
 "end_item": 75,
 "has_more": false,
 "next_page_token": 77,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 62,
    "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,
    "moderated": false,
    "new_users_moderated": false,
    "unmoderate_users_after": 73,
    "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,
    "has_cover_photo": false,
    "has_icon": false,
    "parent_group_id": 17,
    "org_id": 59,
    "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": 80,
    "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": 5,
    "auto_moderate_threads": false,
    "moderate_threads_after": 6,
    "subgroupcategoryid": 74,
    "subs_count": 44,
    "pending_subs_count": 23,
    "pending_msgs_count": 94,
    "open_chats_count": 22,
    "threads_count": 33,
    "messages_count": 74,
    "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_monthly",
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View Group List 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 .
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": 10,
 "start_item": 30,
 "end_item": 95,
 "has_more": false,
 "next_page_token": 14,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 23,
    "object": "groupalias",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "name": "example",
    "alias_group_id": 50,
   }
 ],
}
View Group Alias List definition

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.

GET /api/v1/getperms

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

Example Successful Response

 {
 "object": "perms",
 "manage_subgroups": false,
 "delete_group": false,
 "download_archives": false,
 "download_entire_group": false,
 "download_members": false,
 "view_activity": 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,
 "view_databases": false,
 "can_post": false,
 "can_vote": false,
 "manage_polls": false,
 "view_photos": false,
 "manage_photos": false,
 "manage_members": false,
 "view_calendar": false,
 "manage_calendar": false,
 "view_chats": false,
 "manage_chats": false,
 "view_member_directory": false,
 "view_files": false,
 "manage_files": false,
 "view_members": false,
 "view_wiki": false,
 "manage_wiki": false,
 "manage_subscription": false,
 "public_page": false,
 "sub_page": false,
 "mod_page": false,
 "archives_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,
}
View Perms 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

Name.
alias
optional
string

Alias.
desc
optional
string

Description.
subject_tag
optional
string

Subject tag.
footer
optional
string

Message footer.
website
optional
string

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

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

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

For a subgroup, can be sub_group_privacy_limited_archives, sub_group_privacy_archives, sub_group_privacy_unlisted, sub_group_privacy_none, 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.
lock_group
optional
boolean
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.

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": 9,
 "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,
 "moderated": false,
 "new_users_moderated": false,
 "unmoderate_users_after": 77,
 "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,
 "has_cover_photo": false,
 "has_icon": false,
 "parent_group_id": 45,
 "org_id": 71,
 "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": 8,
 "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": 34,
 "auto_moderate_threads": false,
 "moderate_threads_after": 79,
 "subgroupcategoryid": 54,
 "subs_count": 21,
 "pending_subs_count": 87,
 "pending_msgs_count": 26,
 "open_chats_count": 10,
 "threads_count": 21,
 "messages_count": 67,
 "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_monthly",
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
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.
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": ""
 }

Hashtags

Get Hashtags

Get hashtags

Permissions Needed

You must have the hashtags_visible 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.
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.
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": 1,
 "start_item": 49,
 "end_item": 88,
 "has_more": false,
 "next_page_token": 20,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 74,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 1,
    "name": "",
    "alias": 
      {
      },
    "mods_only_post": false,
    "mods_only_replies": false,
    "no_email": false,
    "moderated": false,
    "special": false,
    "replies_unmoderated": false,
    "locked": false,
    "until": "hash_tag_delete_day",
    "close_instead_of_delete": false,
    "description": "",
    "color_name": "tag_antique_pink",
    "color_hex": "",
    "reply_to": "thread_reply_group_default",
    "topic_count": 40,
    "last_message_date": "2009-11-10T15:00:00-08:00",
   }
 ],
}
View Hashtag List definition

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.
api_key
optional
string

If you have an API key, specify it here.
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&api_key=nonce

Example Successful Response

 {
 "token": "aabbffed2213234",
 "user": 
   {
    "id": 73,
    "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": "",
    "home_page": "",
    "subscriptions": [
      {
       "id": 96,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 66,
       "group_id": 75,
       "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": 10,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_email",
       "pending_sub_notify": "sub_notify_email",
       "sub_notify": "sub_notify_email",
       "storage_notify": "sub_notify_email",
       "sub_group_notify": "sub_notify_email",
       "message_report_notify": "sub_notify_email",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "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": 72,
       "pending_subs": 13,
       "pending_msgs": 14,
       "perms": 
         {
          "object": "perms",
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": 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,
          "view_databases": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "view_photos": false,
          "manage_photos": false,
          "manage_members": false,
          "view_calendar": false,
          "manage_calendar": false,
          "view_chats": false,
          "manage_chats": false,
          "view_member_directory": false,
          "view_files": false,
          "manage_files": false,
          "view_members": false,
          "view_wiki": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_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,
         },
      }
    ],
   },
}
View Login definition

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

 {
 "token": "aabbffed2213234",
 "user": 
   {
    "id": 59,
    "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": "",
    "home_page": "",
    "subscriptions": [
      {
       "id": 25,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 46,
       "group_id": 21,
       "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_email",
       "pending_sub_notify": "sub_notify_email",
       "sub_notify": "sub_notify_email",
       "storage_notify": "sub_notify_email",
       "sub_group_notify": "sub_notify_email",
       "message_report_notify": "sub_notify_email",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "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": 63,
       "pending_subs": 36,
       "pending_msgs": 87,
       "perms": 
         {
          "object": "perms",
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": 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,
          "view_databases": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "view_photos": false,
          "manage_photos": false,
          "manage_members": false,
          "view_calendar": false,
          "manage_calendar": false,
          "view_chats": false,
          "manage_chats": false,
          "view_member_directory": false,
          "view_files": false,
          "manage_files": false,
          "view_members": false,
          "view_wiki": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_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,
         },
      }
    ],
   },
}
View 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": ""
 }

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

 {
 "token": "aabbffed2213234",
 "user": 
   {
    "id": 88,
    "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": "",
    "home_page": "",
    "subscriptions": [
      {
       "id": 23,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 25,
       "group_id": 26,
       "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": 19,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_email",
       "pending_sub_notify": "sub_notify_email",
       "sub_notify": "sub_notify_email",
       "storage_notify": "sub_notify_email",
       "sub_group_notify": "sub_notify_email",
       "message_report_notify": "sub_notify_email",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "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": 0,
       "pending_subs": 14,
       "pending_msgs": 30,
       "perms": 
         {
          "object": "perms",
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": 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,
          "view_databases": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "view_photos": false,
          "manage_photos": false,
          "manage_members": false,
          "view_calendar": false,
          "manage_calendar": false,
          "view_chats": false,
          "manage_chats": false,
          "view_member_directory": false,
          "view_files": false,
          "manage_files": false,
          "view_members": false,
          "view_wiki": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_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,
         },
      }
    ],
   },
}
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
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
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": 76,
 "object": "member_notice",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "group_id": 0,
 "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
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
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": 51,
 "object": "member_notice",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "group_id": 34,
 "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.
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.
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 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": 19,
 "start_item": 66,
 "end_item": 13,
 "has_more": false,
 "next_page_token": 45,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 41,
    "object": "member_notice",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 42,
    "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.
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": 39,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 94,
 "group_id": 21,
 "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": 74,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 1,
 "pending_subs": 50,
 "pending_msgs": 85,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
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.
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": 88,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 64,
 "group_id": 60,
 "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": 16,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 19,
 "pending_subs": 82,
 "pending_msgs": 16,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
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.
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": 13,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 16,
 "group_id": 22,
 "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_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 55,
 "pending_subs": 77,
 "pending_msgs": 63,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
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.
Returns

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

Additional Errors
bad_request

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

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

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

Is returned if the adds require approval. The adds will take place once they have been reviewed.
Notes
  • 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": 17,
 "errors": [
   {
    "object": "direct_add_error",
    "email": "",
    "status": "",
    "group_id": 58,
   }
 ],
 "added_members": [
   {
    "id": 32,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 79,
    "group_id": 75,
    "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": 33,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 40,
    "pending_subs": 27,
    "pending_msgs": 34,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
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 view_members 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
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": 52,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 28,
 "group_id": 37,
 "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": 47,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 69,
 "pending_subs": 12,
 "pending_msgs": 46,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
View Member Info 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 view_members 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. 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'.
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
No additional errors
Notes
  • If you do not have the manage_pending_members permission, you cannot specify the type pending.
  • If you do not have the ban_members permission, you cannot specify the type banned.

GET /api/v1/getmembers

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

Example Successful Response

 {
 "object": "list",
 "total_count": 9,
 "start_item": 4,
 "end_item": 56,
 "has_more": false,
 "next_page_token": 14,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 89,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 23,
    "group_id": 42,
    "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_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 39,
    "pending_subs": 30,
    "pending_msgs": 19,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View Member Info List definition

Example Error Response

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

Get Past Members

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

Permissions Needed

You must have the view_members permission to use this call. In addition, the group must be a Premium or Enterprise 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
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, reason, created.
sort_dir
optional
string

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

Returns a past member 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/getpastmembers

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

Example Successful Response

 {
 "object": "list",
 "total_count": 53,
 "start_item": 60,
 "end_item": 94,
 "has_more": false,
 "next_page_token": 85,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 21,
    "object": "past_member",
    "created": "2009-11-10T15:00:00-08:00",
    "action": "spamleft",
    "member_info": 
      {
       "id": 13,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 1,
       "group_id": 28,
       "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": 57,
       "mod_status": "sub_modstatus_moderator",
       "pending_msg_notify": "sub_notify_email",
       "pending_sub_notify": "sub_notify_email",
       "sub_notify": "sub_notify_email",
       "storage_notify": "sub_notify_email",
       "sub_group_notify": "sub_notify_email",
       "message_report_notify": "sub_notify_email",
       "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
       "owner_msg_notify": "sub_ownermsg_notify_all",
       "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": 84,
       "pending_subs": 62,
       "pending_msgs": 83,
       "perms": 
         {
          "object": "perms",
          "manage_subgroups": false,
          "delete_group": false,
          "download_archives": false,
          "download_entire_group": false,
          "download_members": false,
          "view_activity": 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,
          "view_databases": false,
          "can_post": false,
          "can_vote": false,
          "manage_polls": false,
          "view_photos": false,
          "manage_photos": false,
          "manage_members": false,
          "view_calendar": false,
          "manage_calendar": false,
          "view_chats": false,
          "manage_chats": false,
          "view_member_directory": false,
          "view_files": false,
          "manage_files": false,
          "view_members": false,
          "view_wiki": false,
          "manage_wiki": false,
          "manage_subscription": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_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,
         },
      },
   }
 ],
}
View Past Member List definition

Example Error Response

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

Remove Member

Remove a member from a group.

Permissions Needed

You must have the remove_members permission to use this call.

POST Parameters
group_id
required
number

ID of the group. 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.
Returns

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

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

POST /api/v1/removemember

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

Example Successful Response

 {
 "id": 21,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 50,
 "group_id": 15,
 "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_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 92,
 "pending_subs": 42,
 "pending_msgs": 91,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
View Member Info definition

Example Error Response

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

Search Members

Search the members of a group. The search is over email addresses and full names. 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_members 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.
q
required
string

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

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

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

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

Sort direction. Can be 'asc' or 'desc'.
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
No additional errors

GET /api/v1/searchmembers

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

Example Successful Response

 {
 "object": "list",
 "total_count": 98,
 "start_item": 1,
 "end_item": 7,
 "has_more": false,
 "next_page_token": 12,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 95,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 16,
    "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": 83,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 55,
    "pending_subs": 69,
    "pending_msgs": 40,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View Member Info List definition

Example Error Response

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

Send A Bounce Probe

Send a bounce probe.

Permissions Needed

You must have the manage_member_subscription_options permission to use this call.

POST Parameters
group_id
required
number

ID of the group. 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.
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
bad_request

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

POST /api/v1/sendbounceprobe

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

Example Successful Response

 {
 "id": 94,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 98,
 "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": 17,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 82,
 "pending_subs": 14,
 "pending_msgs": 70,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
View Member Info definition

Example Error Response

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

Send A Confirmation Email

Send a confirmation email.

Permissions Needed

You must have the manage_member_subscription_options permission to use this call.

POST Parameters
group_id
required
number

ID of the group. 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.
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
bad_request

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

POST /api/v1/sendconfirmation

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

Example Successful Response

 {
 "id": 82,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 68,
 "group_id": 76,
 "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": 26,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 96,
 "pending_subs": 25,
 "pending_msgs": 68,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
View Member Info definition

Example Error Response

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

Send Invites

Send invites.

Permissions Needed

You must have the send_invites 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.
emails
required
string

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

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

NOTE: This call is not yet finished and documented.

Additional Errors
No additional errors

POST /api/v1/invite

$ curl "https://groups.io/api/v1/invite" \
-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": 62,
 "errors": [
   {
    "object": "direct_add_error",
    "email": "",
    "status": "",
    "group_id": 43,
   }
 ],
 "added_members": [
   {
    "id": 51,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 21,
    "group_id": 13,
    "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": 9,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 93,
    "pending_subs": 70,
    "pending_msgs": 37,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View Direct Add Results definition

Example Error Response

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

Update Member

Change a member's subscription.

Permissions Needed

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

POST Parameters
group_id
required
number

ID of the group. 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.
post_status
optional
string

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

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

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

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

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

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

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

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

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

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

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

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

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

Returns 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
"bad_request"

"no owners" is returned if changing the mod_status field will leave the group without any owners.
Notes
  • If email_delivery is switched from either email_delivery_digest or email_delivery_html_digest to one of the non-digest options, and there are pending digest messages, a digest will be generated at this time.

POST /api/v1/updatemember

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

Example Successful Response

 {
 "id": 86,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 41,
 "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": 98,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 85,
 "pending_subs": 1,
 "pending_msgs": 58,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
View Member Info definition

Example Error Response

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

Notifications

These API endpoints deal with device notifications.

Register Device

Register a new device to receive notifications via the Expo notification service.

Permissions Needed

None.

POST Parameters
token
required
string

Device ID token as provided by Expo.
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.a

Additional Errors
"bad_request"

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

POST /api/v1/registerdevice

$ curl "https://groups.io/api/v1/registerdevice" \
-b "cookies.curl" \
-d token=abcdef&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Test Notification

Send a test notification. Sends a test notification to all devices registered to this user. This endpoint is probably temporary.

Permissions Needed

None.

POST Parameters
csrf
required
string

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

Device ID token. If this is not specified, any existing registered tokens will be used.
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 token" is returned if the token is missing or invalid.

POST /api/v1/testnotification

$ curl "https://groups.io/api/v1/testnotification" \
-b "cookies.curl" \
-d csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Photos

These are the API endpoints for albums and photos.

New Photo Album

Create a new photo album. The album is created.

Permissions Needed

You must have the manage_photos 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.
title
required
string

The title of the album.
desc
required
string

The description of the album, in plain text format.
upload_perms
required
string

Who can upload photos to this album. Can be: album_upload_group or album_upload_personal.
csrf
required
string

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

Returns a album 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 title" is returned if the title is missing or invalid.
"bad_request"

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

"invalid upload_perms" is returned if the upload_perms parameter is missing or invalid.

POST /api/v1/newalbum

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

Example Successful Response

 {
 "id": 18,
 "object": "album",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 92,
 "group_id": 35,
 "upload_perms": "",
 "title": "",
 "desc": "",
 "cover_photo_thumbnail_url": "",
 "cover_photo_url": "",
 "total_photos": 15,
}
View Album definition

Example Error Response

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

Update Photo Album

Update a photo album.

Permissions Needed

You must be the owner of the album.

POST Parameters
album_id
required
number

ID of the album.
title
optional
string

The title of the album.
desc
optional
string

The description of the album, in plain text format.
upload_perms
optional
string

Who can upload photos to this album. Can be: album_upload_group or album_upload_personal.
csrf
required
string

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

Returns a album 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 album_id" is returned if the album_id is missing or invalid.
"bad_request"

"invalid title" is returned if the title is invalid.
"bad_request"

"invalid desc" is returned if the desc is invalid.
"bad_request"

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

POST /api/v1/updatealbum

$ curl "https://groups.io/api/v1/updatealbum" \
-b "cookies.curl" \
-d album_id=32&title=Test&desc=testing&csrf=1234

Example Successful Response

 {
 "id": 81,
 "object": "album",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 48,
 "group_id": 56,
 "upload_perms": "",
 "title": "",
 "desc": "",
 "cover_photo_thumbnail_url": "",
 "cover_photo_url": "",
 "total_photos": 17,
}
View Album definition

Example Error Response

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

Get Photo Albums

Get photo albums. ALbums are returned using the pagination request and object format.

Permissions Needed

You must have the view_photos 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: title, created.
sort_dir
optional
string

Sort direction. Can be asc or desc.
Returns

Returns an album list object if successful. Returns an error if there is an error.

Additional Errors
No additional errors
Notes
  • Depending on settings, the first album returned may be the Emailed Photos album, which is an album of photos that were sent through messages. This album will have an ID of 0.

GET /api/v1/getalbums

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

Example Successful Response

 {
 "object": "list",
 "total_count": 74,
 "start_item": 99,
 "end_item": 73,
 "has_more": false,
 "next_page_token": 51,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "id": 61,
    "object": "album",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 60,
    "group_id": 92,
    "upload_perms": "",
    "title": "",
    "desc": "",
    "cover_photo_thumbnail_url": "",
    "cover_photo_url": "",
    "total_photos": 24,
   }
 ],
}
View Album List definition

Example Error Response

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

Delete Photo Album

Delete a photo album. Any photos within the album that you have permission to delete will be removed. If the photo album is then empty, it is deleted. In order to delete a photo, you must either be the owner of the photo or a moderator/owner of the group.

Permissions Needed

You must be the owner of the album.

POST Parameters
album_id
required
number

ID of the album.
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 group_id" is returned if the group id is missing or invalid.
"bad_request"

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

POST /api/v1/deletealbum

$ curl "https://groups.io/api/v1/deletealbum" \
-b "cookies.curl" \
-d album_id=32&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Add Photos

Add photos.

Permissions Needed

You must have permission to add photos to the album.

Query Parameters
album_id
required
number

ID of the photo album to add the photo to.
fileupload
required
multipart file

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

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

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

Additional Errors
"bad_request"

"invalid album_id" is returned if the album id is missing or invalid.

POST /api/v1/addphotos

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

Example Successful Response

 {
 "object": "list",
 "total_count": 14,
 "start_item": 18,
 "end_item": 63,
 "has_more": false,
 "next_page_token": 35,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "album": 
   {
    "id": 48,
    "object": "album",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 50,
    "group_id": 40,
    "upload_perms": "",
    "title": "",
    "desc": "",
    "cover_photo_thumbnail_url": "",
    "cover_photo_url": "",
    "total_photos": 52,
   },
 "data": [
   {
    "id": 90,
    "object": "photo",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 66,
    "group_id": 99,
    "name": "",
    "desc": "",
    "media_type": "image/jpeg",
    "size": 60,
    "attachment_num": 94,
    "width": 10,
    "height": 51,
    "album_id": 66,
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
    "format": "gif",
    "focal_length": 3.2,
    "iso": 1,
    "aperture": 3.2,
    "shutter_speed": 22,
    "taken": 60,
    "make": "",
    "model": "",
    "thumbnail_url": "",
    "download_url": "",
   }
 ],
}
View Photo List definition

Example Error Response

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

Update Photo

Update a photo.

Permissions Needed

You must be the owner of the photo.

POST Parameters
photo_id
required
number

ID of the photo.
name
optional
string

The name of the photo
desc
optional
string

The description of the photo, in plain text format.
cover_photo
optional
bool

If true, make this photo the cover photo for the album.
rotate
optional
number

Degrees to rotate the photo, in increments of 90 degrees. Can be: 90, 180, 270, -90, -180, -270.
album_id
optional
number

If provided, this moves the photo to the album. You must have permission to add photos to that album and the album must be in the same group.
csrf
required
string

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

Returns a photo 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 photo_id" is returned if the photo_id is missing or invalid.
"bad_request"

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

"invalid desc" is returned if the desc is invalid.
"bad_request"

"invalid rotate" is returned if the rotate parameter is invalid.
"bad_request"

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

POST /api/v1/updatephoto

$ curl "https://groups.io/api/v1/updatephoto" \
-b "cookies.curl" \
-d photo_id=32&name=Test&desc=testing&csrf=1234

Example Successful Response

 {
 "id": 34,
 "object": "album",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 13,
 "group_id": 62,
 "upload_perms": "",
 "title": "",
 "desc": "",
 "cover_photo_thumbnail_url": "",
 "cover_photo_url": "",
 "total_photos": 98,
}
View Album definition

Example Error Response

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

Get Photo

Get photo.

Permissions Needed

You must have the view_photos 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.
album_id
required
number

ID of the album that contains the photo, or 0 if viewing a photo sent as a message attachment.
photo_id
required
number

ID of the photo to fetch.
attachment_num
required
number

If viewing a photo sent as a message attachment, this is the attachment_num from that photo. If album_id is 0, this field must be specified.
Returns

Returns an photo object if successful. Returns an error if there is an error.

Additional Errors
"bad_request"

"invalid album_id" is returned if the album id is invalid or you do not have permission to view it.
"bad_request"

"invalid photo_id" is returned if the photo id is missing or invalid or you do not have permission to view it.

GET /api/v1/getphoto

$ curl "https://groups.io/api/v1/getphoto?group_id=12&album_id=0&photo_id=12&attachment_num=2" \
-b "cookies.curl"

Example Successful Response

 {
 "id": 17,
 "object": "photo",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 93,
 "group_id": 40,
 "name": "",
 "desc": "",
 "media_type": "image/jpeg",
 "size": 53,
 "attachment_num": 18,
 "width": 1,
 "height": 6,
 "album_id": 88,
 "display_name": "",
 "user_name": "",
 "profile_photo_url": "",
 "profile_privacy": "",
 "email": "",
 "format": "gif",
 "focal_length": 3.2,
 "iso": 71,
 "aperture": 3.2,
 "shutter_speed": 77,
 "taken": 42,
 "make": "",
 "model": "",
 "thumbnail_url": "",
 "download_url": "",
}
View Photo definition

Example Error Response

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

Get Photos

Get photos. Photos are returned using the pagination request and object format.

Permissions Needed

You must have the view_photos 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.
album_id
required
number

ID of the photo album to view.
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, name, taken.
sort_dir
optional
string

Sort direction. Can be asc or desc.
Returns

Returns an photo list object if successful. Returns an error if there is an error.

Additional Errors
"bad_request"

"invalid album_id" is returned if the album id is missing or invalid.
Notes
  • To view the Emailed Photos album, pass in an album_id of 0.

GET /api/v1/getphotos

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

Example Successful Response

 {
 "object": "list",
 "total_count": 17,
 "start_item": 7,
 "end_item": 84,
 "has_more": false,
 "next_page_token": 50,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "album": 
   {
    "id": 7,
    "object": "album",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 22,
    "group_id": 45,
    "upload_perms": "",
    "title": "",
    "desc": "",
    "cover_photo_thumbnail_url": "",
    "cover_photo_url": "",
    "total_photos": 35,
   },
 "data": [
   {
    "id": 48,
    "object": "photo",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 30,
    "group_id": 4,
    "name": "",
    "desc": "",
    "media_type": "image/jpeg",
    "size": 62,
    "attachment_num": 52,
    "width": 75,
    "height": 14,
    "album_id": 7,
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
    "format": "gif",
    "focal_length": 3.2,
    "iso": 53,
    "aperture": 3.2,
    "shutter_speed": 1,
    "taken": 73,
    "make": "",
    "model": "",
    "thumbnail_url": "",
    "download_url": "",
   }
 ],
}
View Photo List definition

Example Error Response

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

Search Photos

Search photos. Photos are returned using the pagination request and object format.

Permissions Needed

You must have the view_photos 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: created, name, taken.
sort_dir
optional
string

Sort direction. Can be asc or desc.
Returns

Returns an photo 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.

GET /api/v1/searchphotos

$ curl "https://groups.io/api/v1/searchphotos?group_id=12&q=Test" \
-b "cookies.curl"

Example Successful Response

 {
 "object": "list",
 "total_count": 1,
 "start_item": 95,
 "end_item": 50,
 "has_more": false,
 "next_page_token": 45,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "album": 
   {
    "id": 27,
    "object": "album",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 99,
    "group_id": 38,
    "upload_perms": "",
    "title": "",
    "desc": "",
    "cover_photo_thumbnail_url": "",
    "cover_photo_url": "",
    "total_photos": 99,
   },
 "data": [
   {
    "id": 15,
    "object": "photo",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 75,
    "group_id": 43,
    "name": "",
    "desc": "",
    "media_type": "image/jpeg",
    "size": 40,
    "attachment_num": 60,
    "width": 39,
    "height": 93,
    "album_id": 51,
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
    "format": "gif",
    "focal_length": 3.2,
    "iso": 12,
    "aperture": 3.2,
    "shutter_speed": 78,
    "taken": 81,
    "make": "",
    "model": "",
    "thumbnail_url": "",
    "download_url": "",
   }
 ],
}
View Photo List definition

Example Error Response

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

Delete Photo

Delete a photo.

Permissions Needed

You must either be the owner of the photo or a moderator/owner of the group.

POST Parameters
photo_id
required
number

ID of the photo.
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 photo_id" is returned if the photo_id is missing or invalid.

POST /api/v1/deletephoto

$ curl "https://groups.io/api/v1/deletephoto" \
-b "cookies.curl" \
-d photo_id=32&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

Reporting

These is the API endpoint for reporting content.

Report Content

Report content.

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.
report_to
required
string

Where to send the report. Can be: mods, support.
reason
required
string

Reason for the complaint.
csrf
required
string

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

ID of the message object to report. One of message_id, file_id, or photo_id must be included in the request.
file_id
string

ID of the file object to report. One of message_id, file_id, or photo_id must be included in the request.
photo_id
string

ID of the photo object to report. One of message_id, file_id, or photo_id must be included in the request.
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"

"missing reason" is returned if the reason field is missing or empty.
"bad_request"

"invalid report_to" is returned if the report_to field is invalid.
"bad_request"

"missing either message_id, photo_id, or file_id" is returned if an appropriate ID is not included.

POST /api/v1/reportcontent

$ curl "https://groups.io/api/v1/reportcontent" \
-b "cookies.curl" \
-d reason=Inappropriate&message_id=321&report_to=mods&csrf=1234

Successful Response

HTTP 200

Example Error Response

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

User

Get User

Return the user information associated with the logged in user.

GET /api/v1/getuser

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

Example Successful Response

 {
 "id": 6,
 "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": "",
 "home_page": "",
 "subscriptions": [
   {
    "id": 79,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 15,
    "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": 11,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 48,
    "pending_subs": 14,
    "pending_msgs": 93,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View User definition

Example Error Response

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

Update User

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

POST Parameters
csrf
required
string

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

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

New password.
timezone
optional
string

New timezone.
post_pref
optional
string

Posting preference, user_postpref_html, user_postpref_plain, user_postpref_markdown
per_page_pref
optional
string

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

How to display times, standard_time, military_time
date_pref
optional
string

How to display dates, us_date, iso_date, international_date
dont_munge_message_id
optional
boolean

Whether to change the message-id of any posted messages. In the user interface, this is the "I always want copies of my own emails" checkbox.
allow_facebook_login
optional
boolean

Allow login to your account via Facebook.
allow_google_login
optional
boolean

Allow login to your account via Google.
allow_sso_login
optional
boolean

Allow login to your account via Single Sign On.
monday_start
optional
boolean

If the calendar should start on Monday (defaults to Sunday).
Returns

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

Additional Errors
bad_request

"same email" is returned if the new email address is the same as the old email address.
bad_request

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

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

"password too short" is returend if the password is too short.
Notes
  • If the email address of the user has changed, a new authentication cookie will be set.

POST /api/v1/updateuser

$ curl "https://groups.io/api/v1/updateuser" \
-b "cookies.curl" \
-d email=test@example.com \
-d csrf=12345

Example Successful Response

 {
 "id": 36,
 "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": "",
 "home_page": "",
 "subscriptions": [
   {
    "id": 55,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 60,
    "group_id": 36,
    "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": 6,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 83,
    "pending_subs": 28,
    "pending_msgs": 1,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View User definition

Example Error Response

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

Update Profile

Updates the authenticated user's profile.

POST Parameters
csrf
required
string

The csrf_token from the user object returned when first logged in.
member_info_id
optional
number

To change the profile information for just one subscription, supply the member_info_id of that subscription.
full_name
optional
string

Your name.
user_name
optional
string

Your user name. Only applicable when member_info_id is not specified.
about_me
optional
string

Your about me section, in HTML format.
location
optional
string

Your location.
website
optional
string

Your website.
profile_privacy
optional
string

Your profile privacy setting. Can be: profile_private, profile_members, profile_public
Returns

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

Additional Errors
bad_request

"invalid member_info_id" is returned if the provided member_info_id is incorrect.
bad_request

"invalid profile_privacy" is returned if the provided profile_privacy is incorrect.

POST /api/v1/updateprofile

$ curl "https://groups.io/api/v1/updateprofile" \
-b "cookies.curl" \
-d full_name=Joe+Smith \
-d "csrf=12345"

Example Successful Response

 {
 "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": "",
 "home_page": "",
 "subscriptions": [
   {
    "id": 79,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 63,
    "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": 87,
    "mod_status": "sub_modstatus_moderator",
    "pending_msg_notify": "sub_notify_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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": 23,
    "pending_msgs": 23,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View User definition

Example Error Response

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

Update Profile Photo

Updates the authenticated user's profile photo.

POST Parameters
csrf
required
string

The csrf_token from the user object returned when first logged in.
imageupload
required
multipart file

Multipart file upload of a new profile photo. The photo can be in GIF or JPEG format.
member_info_id
optional
number

To change the profile photo for just one subscription, supply the member_info_id of that subscription.
Returns

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

Additional Errors
bad_request

"invalid member_info_id" is returned if the provided member_info_id is incorrect.

POST /api/v1/updateprofilephoto

$ curl "https://groups.io/api/v1/updateprofilephoto" \
-b "cookies.curl" \
-F fileupload=@path_to_profile_photo \
-F "csrf=12345"

Example Successful Response

 {
 "id": 25,
 "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": "",
 "home_page": "",
 "subscriptions": [
   {
    "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_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View User definition

Example Error Response

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

Delete Profile Photo

Deletes the authenticated user's profile photo.

POST Parameters
csrf
required
string

The csrf_token from the user object returned when first logged in.
member_info_id
optional
number

To delete the profile photo for just one subscription, supply the member_info_id of that subscription.
Returns

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

Additional Errors
bad_request

"invalid member_info_id" is returned if the provided member_info_id is incorrect.

POST /api/v1/deleteprofilephoto

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

Example Successful Response

 {
 "id": 59,
 "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": "",
 "home_page": "",
 "subscriptions": [
   {
    "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_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View User definition

Example Error Response

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

Get Subscription

Get a subscription to a single group.

Query Parameters
group_id
required
number

ID of the group.
Returns

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

GET /api/v1/getsub

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

Example Successful Response

 {
 "id": 92,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 38,
 "group_id": 95,
 "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": 97,
 "mod_status": "sub_modstatus_moderator",
 "pending_msg_notify": "sub_notify_email",
 "pending_sub_notify": "sub_notify_email",
 "sub_notify": "sub_notify_email",
 "storage_notify": "sub_notify_email",
 "sub_group_notify": "sub_notify_email",
 "message_report_notify": "sub_notify_email",
 "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
 "owner_msg_notify": "sub_ownermsg_notify_all",
 "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": 44,
 "pending_subs": 78,
 "pending_msgs": 8,
 "perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "download_archives": false,
    "download_entire_group": false,
    "download_members": false,
    "view_activity": 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,
    "view_databases": false,
    "can_post": false,
    "can_vote": false,
    "manage_polls": false,
    "view_photos": false,
    "manage_photos": false,
    "manage_members": false,
    "view_calendar": false,
    "manage_calendar": false,
    "view_chats": false,
    "manage_chats": false,
    "view_member_directory": false,
    "view_files": false,
    "manage_files": false,
    "view_members": false,
    "view_wiki": false,
    "manage_wiki": false,
    "manage_subscription": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_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,
   },
}
View Member Info definition

Example Error Response

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

Get Subscriptions

Get the subscriptions associated with the logged in user. Subscriptions are returned using the pagination request and object format.

Query Parameters
limit
optional
default is 10

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

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

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

Sort direction. Can be asc or .
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.

GET /api/v1/getsubs

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

Example Successful Response

 {
 "object": "list",
 "total_count": 27,
 "start_item": 63,
 "end_item": 54,
 "has_more": false,
 "next_page_token": 52,
 "sort_field": "",
 "second_order": "",
 "query": "",
 "sort_dir": "",
 "data": [
   {
    "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_email",
    "pending_sub_notify": "sub_notify_email",
    "sub_notify": "sub_notify_email",
    "storage_notify": "sub_notify_email",
    "sub_group_notify": "sub_notify_email",
    "message_report_notify": "sub_notify_email",
    "mod_permissions": "sub_perm_banmembers,sub_perm_billing",
    "owner_msg_notify": "sub_ownermsg_notify_all",
    "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,
    "perms": 
      {
       "object": "perms",
       "manage_subgroups": false,
       "delete_group": false,
       "download_archives": false,
       "download_entire_group": false,
       "download_members": false,
       "view_activity": 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,
       "view_databases": false,
       "can_post": false,
       "can_vote": false,
       "manage_polls": false,
       "view_photos": false,
       "manage_photos": false,
       "manage_members": false,
       "view_calendar": false,
       "manage_calendar": false,
       "view_chats": false,
       "manage_chats": false,
       "view_member_directory": false,
       "view_files": false,
       "manage_files": false,
       "view_members": false,
       "view_wiki": false,
       "manage_wiki": false,
       "manage_subscription": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_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,
      },
   }
 ],
}
View Member Info List definition

Example Error Response

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

Update Subscription

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

POST Parameters
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.
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
signature
optional
string

Signature to be used for signing messages.
sig_format
optional
string

Format of the signature, can be sig_format_html, sig_format_markdown, sig_format_plain. Ignored if signature is also not specified.
use_signature
optional
boolean

Whether to use the signature for posts originating from the Groups.io website.
use_signature_email
optional
boolean

Whether to use the signature for posts originated from email.
The following are ignored if the subscription `mod_status` is `mod_status_none`.
pending_msg_notify
optional
string

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

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

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

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

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