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

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 view_archives 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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "group_perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
   },
 "group": 
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
      },
   },
 "sub_data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   }
 ],
 "data": [
   {
    "id": 12,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 12,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "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 view_archives 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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "group_perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
   },
 "group": 
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
      },
   },
 "cover_photo_url": "",
 "sub_data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   }
 ],
 "topic": 
   {
    "id": 12,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 12,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   },
 "data": [
   {
    "id": 12,
    "object": "message",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "topic_id": 12,
    "body": "",
    "quoted": "",
    "remainder": "",
    "snippet": "",
    "subject": "",
    "name": "",
    "profile_photo_url": "",
    "is_plain_text": false,
    "msg_num": 12,
    "has_liked": false,
    "num_likes": 12,
    "is_closed": false,
    "is_moderated": false,
    "reply_to": "group_reply_only_to_sender",
    "can_repost": false,
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "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 view_archives 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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "group_perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
   },
 "group": 
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
      },
   },
 "cover_photo_url": "",
 "sub_data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   }
 ],
 "topic": 
   {
    "id": 12,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 12,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   },
 "data": [
   {
    "id": 12,
    "object": "message",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "topic_id": 12,
    "body": "",
    "quoted": "",
    "remainder": "",
    "snippet": "",
    "subject": "",
    "name": "",
    "profile_photo_url": "",
    "is_plain_text": false,
    "msg_num": 12,
    "has_liked": false,
    "num_likes": 12,
    "is_closed": false,
    "is_moderated": false,
    "reply_to": "group_reply_only_to_sender",
    "can_repost": false,
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "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 view_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": ""
 }

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.
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": 12,
 "object": "chat",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "subject": "The chat subject",
 "desc": "This is the description of the chat",
 "is_closed": false,
 "num_messages": 12,
 "chat_sub": 
   {
    "id": 12,
    "object": "chat_sub",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "chat_id": 12,
    "last_msg_seen": 12,
   },
}
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": 12,
 "group_id": 12,
 "subject": "The chat subject",
 "desc": "This is the description of the chat",
 "is_closed": false,
 "num_messages": 12,
 "chat_sub": 
   {
    "id": 12,
    "object": "chat_sub",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "chat_id": 12,
    "last_msg_seen": 12,
   },
}
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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "chat",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "subject": "The chat subject",
    "desc": "This is the description of the chat",
    "is_closed": false,
    "num_messages": 12,
    "chat_sub": 
      {
       "id": 12,
       "object": "chat_sub",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "chat_id": 12,
       "last_msg_seen": 12,
      },
   }
 ],
}
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": 12,
 "object": "chat_sub",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "chat_id": 12,
 "last_msg_seen": 12,
}
View Chat Sub definition

Example Error Response

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

Leave Chat

Leave a 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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "chat_message",
    "created": "2009-11-10T15:00:00-08:00",
    "version": 12,
    "user_id": 12,
    "group_id": 12,
    "chat_id": 12,
    "type": "chat_msg_type_closed",
    "message": "",
    "msg_num": 12,
    "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": 12,
 "object": "draft",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "draft_type": "",
 "subject": "",
 "body": "",
 "body_type": "",
 "is_special": false,
 "num_attachments": 12,
 "next_attachment_id": 12,
 "message_id": 12,
 "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": 12,
 "object": "draft",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "draft_type": "",
 "subject": "",
 "body": "",
 "body_type": "",
 "is_special": false,
 "num_attachments": 12,
 "next_attachment_id": 12,
 "message_id": 12,
 "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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "draft",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "draft_type": "",
    "subject": "",
    "body": "",
    "body_type": "",
    "is_special": false,
    "num_attachments": 12,
    "next_attachment_id": 12,
    "message_id": 12,
    "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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "draft_attachment",
    "draft_id": 12,
    "url": "",
    "filename": "",
    "size": 12,
    "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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "draft_attachment",
    "draft_id": 12,
    "url": "",
    "filename": "",
    "size": 12,
    "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": 12,
 "object": "event",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "creator_name": "@JohnSmith",
 "group_id": 12,
 "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": 12,
 "additional_guests": false,
 "comment_label": "",
 "yes_message": "",
 "has_rsvp": false,
 "rsvp_type": "",
 "rsvp_comment": "",
 "rsvp_additional_guests": 12,
}
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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "event",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "creator_name": "@JohnSmith",
    "group_id": 12,
    "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": 12,
    "additional_guests": false,
    "comment_label": "",
    "yes_message": "",
    "has_rsvp": false,
    "rsvp_type": "",
    "rsvp_comment": "",
    "rsvp_additional_guests": 12,
   }
 ],
}
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": 12,
 "object": "rsvp",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "event_id": 12,
 "group_id": 12,
 "user_id": 12,
 "user_name": "",
 "full_name": "",
 "email": "",
 "profile_photo_id": "",
 "type": "rsvp_maybe",
 "comment": "",
 "additional_guests": 12,
}
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
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 .

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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "object": "feed",
    "member_info": 
      {
       "id": 12,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "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": 12,
       "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": "",
       "full_name": "",
       "about_me": "",
       "about_format": "",
       "location": "",
       "website": "",
       "profile_photo_id": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "use_signature": false,
       "use_signature_email": false,
      },
    "group": 
      {
       "id": 12,
       "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": 12,
       "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": 12,
       "org_id": 12,
       "max_photo_size_email": "max_photo_size_ex_small",
       "max_photo_size_photos": "max_photo_size_ex_small",
       "max_photo_size_databases": "max_photo_size_ex_small",
       "max_photo_size_wiki_images": "max_photo_size_ex_small",
       "hash_tags_required": false,
       "hash_tag_permissions": "hash_tag_create_mods_bounce",
       "bounce_attachments": false,
       "allow_photos_in_files": false,
       "allow_reposts": false,
       "min_days_between_reposts": 12,
       "max_number_of_reposts": 12,
       "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": 12,
       "auto_moderate_threads": false,
       "moderate_threads_after": 12,
       "subgroupcategoryid": 12,
       "subs_count": 12,
       "pending_subs_count": 12,
       "pending_msgs_count": 12,
       "open_chats_count": 12,
       "threads_count": 12,
       "messages_count": 12,
       "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,
          "view_archives": 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,
          "view_guidelines": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_visible": false,
          "members_visible": false,
          "polls_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
         },
      },
    "topics": [
      {
       "topic": 
         {
          "id": 12,
          "object": "topic",
          "created": "2009-11-10T15:00:00-08:00",
          "updated": "2009-11-10T15:00:00-08:00",
          "group_id": 12,
          "group_subject_tag": "",
          "subject": "",
          "summary": "",
          "name": "",
          "profile_photo_url": "",
          "num_messages": 12,
          "is_sticky": false,
          "is_moderated": false,
          "is_closed": false,
          "has_attachments": false,
          "reply_to": "thread_reply_group_default",
          "most_recent_message": "2009-11-10T15:00:00-08:00",
          "hashtags": [
            {
             "id": 12,
             "object": "hashtag",
             "created": "2009-11-10T15:00:00-08:00",
             "group_id": 12,
             "name": "",
             "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": 12,
             "last_message_date": "2009-11-10T15:00:00-08:00",
            }
          ],
         },
       "images": [
         {
          "id": "",
          "object": "attachment",
          "created": "2009-11-10T15:00:00-08:00",
          "group_id": 12,
          "user_id": 12,
          "thread_id": 12,
          "message_num": 12,
          "attach_num": 12,
          "type": "",
          "sub_type": "",
          "name": "",
          "content": "",
          "image_width": 12,
          "image_height": 12,
          "column:gallery_url": "",
         }
       ],
      }
    ],
    "events": [
      {
       "id": 12,
       "object": "event",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "creator_name": "@JohnSmith",
       "group_id": 12,
       "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": 12,
       "additional_guests": false,
       "comment_label": "",
       "yes_message": "",
       "has_rsvp": false,
       "rsvp_type": "",
       "rsvp_comment": "",
       "rsvp_additional_guests": 12,
      }
    ],
    "files": [
      {
       "id": 12,
       "object": "file",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "name": "",
       "desc": "",
       "media_type": "",
       "size": 12,
       "parent_dir_id": 12,
      }
    ],
    "photos": [
      {
       "id": 12,
       "object": "photo",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "name": "",
       "desc": "",
       "media_type": "",
       "size": 12,
       "column:width": 12,
       "column:height": 12,
       "column:album_id": 12,
       "format": "",
       "focal_length": 3.2,
       "iso": 12,
       "aperture": 3.2,
       "shutter_speed": 12,
       "taken": 12,
       "make": "",
       "model": "",
       "column:gallery_url": "",
      }
    ],
    "chats": [
      {
       "id": 12,
       "object": "chat",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "subject": "The chat subject",
       "desc": "This is the description of the chat",
       "is_closed": false,
       "num_messages": 12,
       "chat_sub": 
         {
          "id": 12,
          "object": "chat_sub",
          "created": "2009-11-10T15:00:00-08:00",
          "updated": "2009-11-10T15:00:00-08:00",
          "user_id": 12,
          "group_id": 12,
          "chat_id": 12,
          "last_msg_seen": 12,
         },
      }
    ],
    "wikis": [
      {
       "id": 12,
       "object": "wiki",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "title": "",
       "desc": "",
       "format": "",
       "locked": false,
       "rev_count": 12,
      }
    ],
    "subgroups": [
      {
       "id": 12,
       "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": 12,
       "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": 12,
       "org_id": 12,
       "max_photo_size_email": "max_photo_size_ex_small",
       "max_photo_size_photos": "max_photo_size_ex_small",
       "max_photo_size_databases": "max_photo_size_ex_small",
       "max_photo_size_wiki_images": "max_photo_size_ex_small",
       "hash_tags_required": false,
       "hash_tag_permissions": "hash_tag_create_mods_bounce",
       "bounce_attachments": false,
       "allow_photos_in_files": false,
       "allow_reposts": false,
       "min_days_between_reposts": 12,
       "max_number_of_reposts": 12,
       "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": 12,
       "auto_moderate_threads": false,
       "moderate_threads_after": 12,
       "subgroupcategoryid": 12,
       "subs_count": 12,
       "pending_subs_count": 12,
       "pending_msgs_count": 12,
       "open_chats_count": 12,
       "threads_count": 12,
       "messages_count": 12,
       "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,
          "view_archives": 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,
          "view_guidelines": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_visible": false,
          "members_visible": false,
          "polls_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
         },
      }
    ],
    "tables": [
      {
       "id": 12,
       "object": "databasetable",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "user_id": 12,
       "name": "",
       "short_desc": "",
       "desc": "",
       "desc_type": "",
       "edit_table": "",
       "edit_rows": "",
       "add_rows": "",
       "view_table": "",
       "num_rows": 12,
       "max_row_id": 12,
       "num_columns": 12,
       "max_col_id": 12,
       "display_template": "",
       "columns": [
         {
          "id": 12,
          "name": "",
          "type": "",
          "required": false,
          "color": "",
          "choices": [""],
          "width": 12,
         }
       ],
      }
    ],
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}
View Feed 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": 12,
 "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": 12,
 "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": 12,
 "org_id": 12,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 12,
 "max_number_of_reposts": 12,
 "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": 12,
 "auto_moderate_threads": false,
 "moderate_threads_after": 12,
 "subgroupcategoryid": 12,
 "subs_count": 12,
 "pending_subs_count": 12,
 "pending_msgs_count": 12,
 "open_chats_count": 12,
 "threads_count": 12,
 "messages_count": 12,
 "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,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_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": 12,
 "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": 12,
 "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": 12,
 "org_id": 12,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 12,
 "max_number_of_reposts": 12,
 "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": 12,
 "auto_moderate_threads": false,
 "moderate_threads_after": 12,
 "subgroupcategoryid": 12,
 "subs_count": 12,
 "pending_subs_count": 12,
 "pending_msgs_count": 12,
 "open_chats_count": 12,
 "threads_count": 12,
 "messages_count": 12,
 "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,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_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": 12,
 "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": 12,
 "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": 12,
 "org_id": 12,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 12,
 "max_number_of_reposts": 12,
 "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": 12,
 "auto_moderate_threads": false,
 "moderate_threads_after": 12,
 "subgroupcategoryid": 12,
 "subs_count": 12,
 "pending_subs_count": 12,
 "pending_msgs_count": 12,
 "open_chats_count": 12,
 "threads_count": 12,
 "messages_count": 12,
 "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,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "groupalias",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "name": "example",
    "alias_group_id": 12,
   }
 ],
}
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,
 "view_archives": 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,
 "view_guidelines": false,
 "public_page": false,
 "sub_page": false,
 "mod_page": false,
 "archives_visible": false,
 "members_visible": false,
 "polls_visible": false,
 "chat_visible": false,
 "calendar_visible": false,
 "files_visible": false,
 "database_visible": false,
 "photos_visible": false,
 "wiki_visible": false,
 "member_directory_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": 12,
 "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": 12,
 "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": 12,
 "org_id": 12,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 12,
 "max_number_of_reposts": 12,
 "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": 12,
 "auto_moderate_threads": false,
 "moderate_threads_after": 12,
 "subgroupcategoryid": 12,
 "subs_count": 12,
 "pending_subs_count": 12,
 "pending_msgs_count": 12,
 "open_chats_count": 12,
 "threads_count": 12,
 "messages_count": 12,
 "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,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_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

None.

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.
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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "name": "",
    "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": 12,
    "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": 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": "",
   },
}
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": 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": "",
   },
}
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": 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": "",
   },
}
View Login 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": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": 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": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": 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": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": 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": 12,
 "errors": [
   {
    "object": "direct_add_error",
    "email": "",
    "status": "",
    "group_id": 12,
   }
 ],
 "added_members": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": 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": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": 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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": 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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "past_member",
    "created": "2009-11-10T15:00:00-08:00",
    "action": "spamleft",
    "member_info": 
      {
       "id": 12,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "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": 12,
       "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": "",
       "full_name": "",
       "about_me": "",
       "about_format": "",
       "location": "",
       "website": "",
       "profile_photo_id": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "use_signature": false,
       "use_signature_email": 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": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": 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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": 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": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": 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": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": 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": 12,
 "errors": [
   {
    "object": "direct_add_error",
    "email": "",
    "status": "",
    "group_id": 12,
   }
 ],
 "added_members": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": 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": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": false,
}
View Member Info definition

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": 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": "",
}
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": 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": "",
}
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. 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/getsub

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

Example Successful Response

 {
 "id": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": 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. Note: these subscriptions are subscription_plus objects, containing extra data as detailed in that object.

Query Parameters
limit
optional
default is 10

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

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

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

Sort direction. Can be asc or .

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": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": 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
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 the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid parameter). Below are the unique errors to this call.

Additional Errors
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.

GET /api/v1/updatesub

$ curl "https://groups.io/api/v1/updatesub" \
-b "cookies.curl" \
-d member_info_id=2 \
-d email_delivery=email_delivery_single \
-d csrf=12345

Example Successful Response

 {
 "id": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": false,
}
View Member Info definition

Example Error Response

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

Delete Subscription

Delete a subscription.

POST Parameters
group_id
required

ID of the group from which you wish to unsubscribe.
csrf
required
string

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

"you are the only owner" is returned if you are the only owner of the group.
Notes
  • Every group must have at least one owner. If you are the only owner of the group, you cannot delete your subscription.

POST /api/v1/deletesub

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

Successful Response

HTTP 200

Example Error Response

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

Objects

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

The Add Error Object

The direct add results error object.

Response Attributes
object
string

direct_add_error.
email
string
status
string

utils.DirectAddStatus.
group_id
number

Example Response

{
 "object": "direct_add_error",
 "email": "",
 "status": "",
 "group_id": 12,
}

The Album Object

The album object.

Response Attributes
id
number

Unique ID of the album object.
object
string

album.
created
date
updated
date
user_id
number
group_id
number
upload_perms
string
title
string

Title of the album.
desc
string

Description of the album in plain text.
cover_photo_id
number

Photo to display.
total_photos
number

How many photos in album.

Example Response

{
 "id": 12,
 "object": "album",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "upload_perms": "",
 "title": "",
 "desc": "",
 "cover_photo_id": 12,
 "total_photos": 12,
}

The Album List Object

Album List

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Album objects

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "album",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "upload_perms": "",
    "title": "",
    "desc": "",
    "cover_photo_id": 12,
    "total_photos": 12,
   }
 ],
}

The Attachment Object

The Attachment object contains all the data required for displaying an image attachment.

Response Attributes
id
string
object
string

attachment.
created
date
group_id
number
user_id
number

Who originally created this table.
thread_id
number
message_num
number
attach_num
number
type
string
sub_type
string
name
string
content
string
image_width
number
image_height
number
column

gallery_url - string:

Example Response

{
 "id": "",
 "object": "attachment",
 "created": "2009-11-10T15:00:00-08:00",
 "group_id": 12,
 "user_id": 12,
 "thread_id": 12,
 "message_num": 12,
 "attach_num": 12,
 "type": "",
 "sub_type": "",
 "name": "",
 "content": "",
 "image_width": 12,
 "image_height": 12,
 "column:gallery_url": "",
}

The Chat Object

The chat object.

Response Attributes
id
number

Unique ID of the chat object.
object
string

chat.
created
date
updated
date
user_id
number

ID of the person who created the chat.
group_id
number

ID of the group the chat is in.
subject
string
desc
string
is_closed
boolean
num_messages
number
chat_sub
Chat Sub object

If the calling person is subscribed to this chat, this is their subscription.
Methods That Use This Object
New Chat

View Method
Update Chat

View Method

Example Response

{
 "id": 12,
 "object": "chat",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "subject": "The chat subject",
 "desc": "This is the description of the chat",
 "is_closed": false,
 "num_messages": 12,
 "chat_sub": 
   {
    "id": 12,
    "object": "chat_sub",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "chat_id": 12,
    "last_msg_seen": 12,
   },
}

The Chat List Object

Chat List

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Chat objects
Methods That Use This Object
Get Chats

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "chat",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "subject": "The chat subject",
    "desc": "This is the description of the chat",
    "is_closed": false,
    "num_messages": 12,
    "chat_sub": 
      {
       "id": 12,
       "object": "chat_sub",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "chat_id": 12,
       "last_msg_seen": 12,
      },
   }
 ],
}

The Chat Message Object

The chat message object. A chat message is a posted message to a chat room.

Response Attributes
id
number

Unique ID of the chat_message object.
object
string

chat_message.
created
date
version
number

The version of this object. Used to detect server upgrades to force reload of the app. The current version is 2.
user_id
number

ID of the person who is subscribed.
group_id
number

ID of the group the chat is in.
chat_id
number

ID of the chat.
type
string

Type of message. Can be one of: chat_msg_type_closed, chat_msg_type_first, chat_msg_type_joined, chat_msg_type_left, chat_msg_type_normal.
message
string

The chat message itself (dependant on the Type of chat message), in HTML format.
msg_num
number

The message number, increases monotonically from 1.
display_name
string
user_name
string
profile_photo_url
string
profile_privacy
string

Privacy setting of the sender of the message.
email
string

Possibly obscured, depending on group settings.

Example Response

{
 "id": 12,
 "object": "chat_message",
 "created": "2009-11-10T15:00:00-08:00",
 "version": 12,
 "user_id": 12,
 "group_id": 12,
 "chat_id": 12,
 "type": "chat_msg_type_closed",
 "message": "",
 "msg_num": 12,
 "display_name": "",
 "user_name": "",
 "profile_photo_url": "",
 "profile_privacy": "",
 "email": "",
}

The Chat Message List Object

Chat Message List

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Chat Message objects
Methods That Use This Object
Get Chat History

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "chat_message",
    "created": "2009-11-10T15:00:00-08:00",
    "version": 12,
    "user_id": 12,
    "group_id": 12,
    "chat_id": 12,
    "type": "chat_msg_type_closed",
    "message": "",
    "msg_num": 12,
    "display_name": "",
    "user_name": "",
    "profile_photo_url": "",
    "profile_privacy": "",
    "email": "",
   }
 ],
}

The Chat Post Object

The chat post object. A chat post is the object a client sends to the server containing a message to post to the chat room. It then gets turned into a chat_message and is sent out to every person currently in the chat room, as well as stored in the database. Note that these messages should be in Markdown format and can contain emoji codes. They are converted on the server and returned as HTML in chat_message objects. In addition to posts, commands can be sent. Currently, only the /leave command is supported.

Response Attributes
object
string

chat_post.
type
string

Type of message. This should be set to chat_post_type_post.
message
string

The chat message itself (dependant on the Type of chat message), in Markdown format.

Example Response

{
 "object": "chat_post",
 "type": "chat_post_type_post",
 "message": "Did you hear the news?",
}

The Chat Sub Object

The chat subscription object.

Response Attributes
id
number

Unique ID of the draft object.
object
string

chat_sub.
created
date
updated
date
user_id
number

ID of the person who is subscribed.
group_id
number

ID of the group the chat is in.
chat_id
number

ID of the chat.
last_msg_seen
number

ID of the last chat_message msg_num seen by this subscriber.
Methods That Use This Object
Join Chat

View Method

Example Response

{
 "id": 12,
 "object": "chat_sub",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "chat_id": 12,
 "last_msg_seen": 12,
}

The Database Column Object

The database column object.

Response Attributes
id
number

Column ID.
name
string

Name is the name of the column.
type
string

Type is the column type.
required
boolean

Required means that the field cannot be empty.
color
string

Color is the color of the row.
choices
array of string

Choices are the titles of choices for Multiple Choice column. Also used for YesNo.
width
number

Width is the width of the column (0 means not set/use the default).

Example Response

{
 "id": 12,
 "name": "",
 "type": "",
 "required": false,
 "color": "",
 "choices": [""],
 "width": 12,
}

The Database Table Object

The database table object.

Response Attributes
id
number
object
string

databasetable.
created
date
updated
date
group_id
number
user_id
number

Who originally created this table.
name
string

Name of table.
short_desc
string
desc
string
desc_type
string

html, plain, markdown.
edit_table
string
edit_rows
string
add_rows
string
view_table
string
num_rows
number

Number of rows, not maintained automatically.
max_row_id
number

For setting DatabaseRow.RowID, not maintained automatically.
num_columns
number

Number of columns, automatically maintained.
max_col_id
number

For setting unique column ids.
display_template
string

Display template.
columns
array of Database Column objects

Example Response

{
 "id": 12,
 "object": "databasetable",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "group_id": 12,
 "user_id": 12,
 "name": "",
 "short_desc": "",
 "desc": "",
 "desc_type": "",
 "edit_table": "",
 "edit_rows": "",
 "add_rows": "",
 "view_table": "",
 "num_rows": 12,
 "max_row_id": 12,
 "num_columns": 12,
 "max_col_id": 12,
 "display_template": "",
 "columns": [
   {
    "id": 12,
    "name": "",
    "type": "",
    "required": false,
    "color": "",
    "choices": [""],
    "width": 12,
   }
 ],
}

The Direct Add Results Object

The direct add results object.

Response Attributes
object
string

direct_add_results.
total_emails
number
errors
array of Add Error objects
added_members
array of Member Info objects
Methods That Use This Object
Direct Add

View Method
Send Invites

View Method

Example Response

{
 "object": "direct_add_results",
 "total_emails": 12,
 "errors": [
   {
    "object": "direct_add_error",
    "email": "",
    "status": "",
    "group_id": 12,
   }
 ],
 "added_members": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   }
 ],
}

The Draft Object

The draft object. Draft represents a draft of a posting (a post in process of being written).

Response Attributes
id
number

Unique ID of the draft object.
object
string

draft.
created
date
updated
date
user_id
number

ID of the user who created the draft.
group_id
number

ID of the group the draft was created in.
draft_type
string

The type of message this draft represents.
subject
string

Subject of the draft message.
body
string

Body of the draft message.
body_type
string

Body type of the draft message.
is_special
boolean

If the draft should be sent as a special message. Only applicable for draft_type_post and draft_type_reply.
num_attachments
number

The number of attachments associated with the draft.
next_attachment_id
number

The ID of the next attachment to be uploaded.
message_id
number

message_id is for replies, and is the ID of the Message we're replying to.
bcc_me
boolean

If we should BCC ourselves with the message. Only applicable for draft_type_post_to_sub.
bcc_all
boolean

If we should BCC all moderators with the message. Only applicable for draft_type_post_to_sub.
Methods That Use This Object
New Draft

View Method
Update Draft

View Method

Example Response

{
 "id": 12,
 "object": "draft",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "draft_type": "",
 "subject": "",
 "body": "",
 "body_type": "",
 "is_special": false,
 "num_attachments": 12,
 "next_attachment_id": 12,
 "message_id": 12,
 "bcc_me": false,
 "bcc_all": false,
}

The Draft Attachment Object

The draft attachment object. This represents an attachment associated with a draft.

Response Attributes
id
number

ID of the draft attachment object.
object
string

draft_attachment.
draft_id
number

ID of the draft this attachment is associated with.
url
string

The URL of the draft attachment, for displaying the attachment.
filename
string

Filename of the attachment.
size
number

Size of the attachment.
content_type
string

Content type of the attachment.
inline
boolean

If the attachment represents an inline image.

Example Response

{
 "id": 12,
 "object": "draft_attachment",
 "draft_id": 12,
 "url": "",
 "filename": "",
 "size": 12,
 "content_type": "",
 "inline": false,
}

The Draft Attachment List Object

Draft Attachment List

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Draft Attachment objects
Methods That Use This Object
Upload Attachments

View Method
Get Attachments

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "draft_attachment",
    "draft_id": 12,
    "url": "",
    "filename": "",
    "size": 12,
    "content_type": "",
    "inline": false,
   }
 ],
}

The Draft List Object

Draft List

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Draft objects
Methods That Use This Object
Get Drafts

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "draft",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "draft_type": "",
    "subject": "",
    "body": "",
    "body_type": "",
    "is_special": false,
    "num_attachments": 12,
    "next_attachment_id": 12,
    "message_id": 12,
    "bcc_me": false,
    "bcc_all": false,
   }
 ],
}

The Error Object

The error object.

Response Attributes
object
string

error.
type
string
extra
string

Example Response

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

The Event Object

The event object.

Response Attributes
id
number

Unique ID of the rsvp object.
object
string

event.
created
date

The time that this object was created.
updated
date

The time that this object was last updated.
creator_name
string

Name of the person who created this event.
group_id
number

The ID of the associated group.
group_name
string

Name of the associated group.
nice_group_name
string

Nice version of the group name.
start_time
date

Start time of event.
end_time
date

End time of event.
timezone
string

Timezone that event was created in.
all_day
boolean

If event is all day.
name
string

Name of the event.
location
string

Location of the event.
description
string

Event description, in HTML format.
organizer_name
string

Organizer name.
organizer_email
string

Organizer email.
organizer_phone
string

Organizer phone number.
color_name
string

Name of the event color. Can be one of: tag_antique_pink, tag_apricot, tag_aquamute, tag_beige, tag_bluejean, tag_blush, tag_burnt_yellow, tag_capri_blue, tag_cerulean_blue, tag_cherry_blossom, tag_cloudy_blue, tag_cucumber, tag_dark_grey, tag_dark_orange, tag_dusty_mauve, tag_emerald_green, tag_grape, tag_green_lantern, tag_green_sage, tag_grey_blue, tag_light_brown, tag_light_grey, tag_light_lilac, tag_lilac, tag_lips, tag_melon, tag_military, tag_moss_green, tag_mulbery, tag_mustard, tag_orange, tag_orchid, tag_peony, tag_pink, tag_purple, tag_purple_blue, tag_purple_grey, tag_sage, tag_sky, tag_terracotta, tag_tomato, tag_yellow.
color_hex
string

Hex value of the event color.
rsvp
boolean

Requesting an RSVP.
max_attendees
number

Number of attendees for RSVP events (0 if unlimited).
additional_guests
boolean

Whether attendees can bring additional people.
comment_label
string

If additional information is requested, this is the label for that field.
yes_message
string

Email to send when people RSVP Yes, in same format as Format.
has_rsvp
boolean

If there is an RSVP record for this event corresponding to this user.
rsvp_type
string

Type of RSVP.
rsvp_comment
string

Any comment left with the RSVP.
rsvp_additional_guests
number

Number of additional guests specified by the RSVP.
Methods That Use This Object
Get Event

View Method

Example Response

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

The Event List Object

The Event List object contains a list of Event objects.

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Event objects
Methods That Use This Object
Get Events

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "event",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "creator_name": "@JohnSmith",
    "group_id": 12,
    "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": 12,
    "additional_guests": false,
    "comment_label": "",
    "yes_message": "",
    "has_rsvp": false,
    "rsvp_type": "",
    "rsvp_comment": "",
    "rsvp_additional_guests": 12,
   }
 ],
}

The Feed Object

The Feed object contains all the data required for displaying one group in a user's feed page.

Response Attributes
object
string

feed.
member_info
Member Info object
group
Group object
topics
array of Feed Topic objects

The five most recent topics.
events
array of Event objects

The next four upcoming events.
files
array of File objects

The five most recent file uploads.
photos
array of Photo objects

The nine most recent photo uploads.
chats
array of Chat objects

The five most recent chats.
wikis
array of Wiki objects

The five most recently updated wiki pages.
subgroups
array of Group objects

The five newest subgroups, if this is a parent group.
tables
array of Database Table objects

The five most recently updated database tables.
hashtags
array of Hashtag objects

The ten most popular hashtags.

Example Response

{
 "object": "feed",
 "member_info": 
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   },
 "group": 
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
      },
   },
 "topics": [
   {
    "topic": 
      {
       "id": 12,
       "object": "topic",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "group_subject_tag": "",
       "subject": "",
       "summary": "",
       "name": "",
       "profile_photo_url": "",
       "num_messages": 12,
       "is_sticky": false,
       "is_moderated": false,
       "is_closed": false,
       "has_attachments": false,
       "reply_to": "thread_reply_group_default",
       "most_recent_message": "2009-11-10T15:00:00-08:00",
       "hashtags": [
         {
          "id": 12,
          "object": "hashtag",
          "created": "2009-11-10T15:00:00-08:00",
          "group_id": 12,
          "name": "",
          "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": 12,
          "last_message_date": "2009-11-10T15:00:00-08:00",
         }
       ],
      },
    "images": [
      {
       "id": "",
       "object": "attachment",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "user_id": 12,
       "thread_id": 12,
       "message_num": 12,
       "attach_num": 12,
       "type": "",
       "sub_type": "",
       "name": "",
       "content": "",
       "image_width": 12,
       "image_height": 12,
       "column:gallery_url": "",
      }
    ],
   }
 ],
 "events": [
   {
    "id": 12,
    "object": "event",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "creator_name": "@JohnSmith",
    "group_id": 12,
    "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": 12,
    "additional_guests": false,
    "comment_label": "",
    "yes_message": "",
    "has_rsvp": false,
    "rsvp_type": "",
    "rsvp_comment": "",
    "rsvp_additional_guests": 12,
   }
 ],
 "files": [
   {
    "id": 12,
    "object": "file",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "name": "",
    "desc": "",
    "media_type": "",
    "size": 12,
    "parent_dir_id": 12,
   }
 ],
 "photos": [
   {
    "id": 12,
    "object": "photo",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "name": "",
    "desc": "",
    "media_type": "",
    "size": 12,
    "column:width": 12,
    "column:height": 12,
    "column:album_id": 12,
    "format": "",
    "focal_length": 3.2,
    "iso": 12,
    "aperture": 3.2,
    "shutter_speed": 12,
    "taken": 12,
    "make": "",
    "model": "",
    "column:gallery_url": "",
   }
 ],
 "chats": [
   {
    "id": 12,
    "object": "chat",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "subject": "The chat subject",
    "desc": "This is the description of the chat",
    "is_closed": false,
    "num_messages": 12,
    "chat_sub": 
      {
       "id": 12,
       "object": "chat_sub",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "chat_id": 12,
       "last_msg_seen": 12,
      },
   }
 ],
 "wikis": [
   {
    "id": 12,
    "object": "wiki",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "title": "",
    "desc": "",
    "format": "",
    "locked": false,
    "rev_count": 12,
   }
 ],
 "subgroups": [
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
      },
   }
 ],
 "tables": [
   {
    "id": 12,
    "object": "databasetable",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "user_id": 12,
    "name": "",
    "short_desc": "",
    "desc": "",
    "desc_type": "",
    "edit_table": "",
    "edit_rows": "",
    "add_rows": "",
    "view_table": "",
    "num_rows": 12,
    "max_row_id": 12,
    "num_columns": 12,
    "max_col_id": 12,
    "display_template": "",
    "columns": [
      {
       "id": 12,
       "name": "",
       "type": "",
       "required": false,
       "color": "",
       "choices": [""],
       "width": 12,
      }
    ],
   }
 ],
 "hashtags": [
   {
    "id": 12,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "name": "",
    "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": 12,
    "last_message_date": "2009-11-10T15:00:00-08:00",
   }
 ],
}

The Feed List Object

The Feed List object contains a list of Feed objects.

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Feed objects
Methods That Use This Object
Get Feed

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "object": "feed",
    "member_info": 
      {
       "id": 12,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "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": 12,
       "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": "",
       "full_name": "",
       "about_me": "",
       "about_format": "",
       "location": "",
       "website": "",
       "profile_photo_id": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "use_signature": false,
       "use_signature_email": false,
      },
    "group": 
      {
       "id": 12,
       "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": 12,
       "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": 12,
       "org_id": 12,
       "max_photo_size_email": "max_photo_size_ex_small",
       "max_photo_size_photos": "max_photo_size_ex_small",
       "max_photo_size_databases": "max_photo_size_ex_small",
       "max_photo_size_wiki_images": "max_photo_size_ex_small",
       "hash_tags_required": false,
       "hash_tag_permissions": "hash_tag_create_mods_bounce",
       "bounce_attachments": false,
       "allow_photos_in_files": false,
       "allow_reposts": false,
       "min_days_between_reposts": 12,
       "max_number_of_reposts": 12,
       "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": 12,
       "auto_moderate_threads": false,
       "moderate_threads_after": 12,
       "subgroupcategoryid": 12,
       "subs_count": 12,
       "pending_subs_count": 12,
       "pending_msgs_count": 12,
       "open_chats_count": 12,
       "threads_count": 12,
       "messages_count": 12,
       "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,
          "view_archives": 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,
          "view_guidelines": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_visible": false,
          "members_visible": false,
          "polls_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
         },
      },
    "topics": [
      {
       "topic": 
         {
          "id": 12,
          "object": "topic",
          "created": "2009-11-10T15:00:00-08:00",
          "updated": "2009-11-10T15:00:00-08:00",
          "group_id": 12,
          "group_subject_tag": "",
          "subject": "",
          "summary": "",
          "name": "",
          "profile_photo_url": "",
          "num_messages": 12,
          "is_sticky": false,
          "is_moderated": false,
          "is_closed": false,
          "has_attachments": false,
          "reply_to": "thread_reply_group_default",
          "most_recent_message": "2009-11-10T15:00:00-08:00",
          "hashtags": [
            {
             "id": 12,
             "object": "hashtag",
             "created": "2009-11-10T15:00:00-08:00",
             "group_id": 12,
             "name": "",
             "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": 12,
             "last_message_date": "2009-11-10T15:00:00-08:00",
            }
          ],
         },
       "images": [
         {
          "id": "",
          "object": "attachment",
          "created": "2009-11-10T15:00:00-08:00",
          "group_id": 12,
          "user_id": 12,
          "thread_id": 12,
          "message_num": 12,
          "attach_num": 12,
          "type": "",
          "sub_type": "",
          "name": "",
          "content": "",
          "image_width": 12,
          "image_height": 12,
          "column:gallery_url": "",
         }
       ],
      }
    ],
    "events": [
      {
       "id": 12,
       "object": "event",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "creator_name": "@JohnSmith",
       "group_id": 12,
       "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": 12,
       "additional_guests": false,
       "comment_label": "",
       "yes_message": "",
       "has_rsvp": false,
       "rsvp_type": "",
       "rsvp_comment": "",
       "rsvp_additional_guests": 12,
      }
    ],
    "files": [
      {
       "id": 12,
       "object": "file",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "name": "",
       "desc": "",
       "media_type": "",
       "size": 12,
       "parent_dir_id": 12,
      }
    ],
    "photos": [
      {
       "id": 12,
       "object": "photo",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "name": "",
       "desc": "",
       "media_type": "",
       "size": 12,
       "column:width": 12,
       "column:height": 12,
       "column:album_id": 12,
       "format": "",
       "focal_length": 3.2,
       "iso": 12,
       "aperture": 3.2,
       "shutter_speed": 12,
       "taken": 12,
       "make": "",
       "model": "",
       "column:gallery_url": "",
      }
    ],
    "chats": [
      {
       "id": 12,
       "object": "chat",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "subject": "The chat subject",
       "desc": "This is the description of the chat",
       "is_closed": false,
       "num_messages": 12,
       "chat_sub": 
         {
          "id": 12,
          "object": "chat_sub",
          "created": "2009-11-10T15:00:00-08:00",
          "updated": "2009-11-10T15:00:00-08:00",
          "user_id": 12,
          "group_id": 12,
          "chat_id": 12,
          "last_msg_seen": 12,
         },
      }
    ],
    "wikis": [
      {
       "id": 12,
       "object": "wiki",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "title": "",
       "desc": "",
       "format": "",
       "locked": false,
       "rev_count": 12,
      }
    ],
    "subgroups": [
      {
       "id": 12,
       "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": 12,
       "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": 12,
       "org_id": 12,
       "max_photo_size_email": "max_photo_size_ex_small",
       "max_photo_size_photos": "max_photo_size_ex_small",
       "max_photo_size_databases": "max_photo_size_ex_small",
       "max_photo_size_wiki_images": "max_photo_size_ex_small",
       "hash_tags_required": false,
       "hash_tag_permissions": "hash_tag_create_mods_bounce",
       "bounce_attachments": false,
       "allow_photos_in_files": false,
       "allow_reposts": false,
       "min_days_between_reposts": 12,
       "max_number_of_reposts": 12,
       "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": 12,
       "auto_moderate_threads": false,
       "moderate_threads_after": 12,
       "subgroupcategoryid": 12,
       "subs_count": 12,
       "pending_subs_count": 12,
       "pending_msgs_count": 12,
       "open_chats_count": 12,
       "threads_count": 12,
       "messages_count": 12,
       "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,
          "view_archives": 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,
          "view_guidelines": false,
          "public_page": false,
          "sub_page": false,
          "mod_page": false,
          "archives_visible": false,
          "members_visible": false,
          "polls_visible": false,
          "chat_visible": false,
          "calendar_visible": false,
          "files_visible": false,
          "database_visible": false,
          "photos_visible": false,
          "wiki_visible": false,
          "member_directory_visible": false,
         },
      }
    ],
    "tables": [
      {
       "id": 12,
       "object": "databasetable",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "user_id": 12,
       "name": "",
       "short_desc": "",
       "desc": "",
       "desc_type": "",
       "edit_table": "",
       "edit_rows": "",
       "add_rows": "",
       "view_table": "",
       "num_rows": 12,
       "max_row_id": 12,
       "num_columns": 12,
       "max_col_id": 12,
       "display_template": "",
       "columns": [
         {
          "id": 12,
          "name": "",
          "type": "",
          "required": false,
          "color": "",
          "choices": [""],
          "width": 12,
         }
       ],
      }
    ],
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}

The Feed Topic Object

The Feed Topic object combines a Topic object and an array of Images that go with the most recent message in that topic.

Response Attributes
topic
Topic object
images
array of Attachment objects

Example Response

{
 "topic": 
   {
    "id": 12,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 12,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   },
 "images": [
   {
    "id": "",
    "object": "attachment",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "user_id": 12,
    "thread_id": 12,
    "message_num": 12,
    "attach_num": 12,
    "type": "",
    "sub_type": "",
    "name": "",
    "content": "",
    "image_width": 12,
    "image_height": 12,
    "column:gallery_url": "",
   }
 ],
}

The File Object

The file object.

Response Attributes
id
number
object
string

file.
created
date
updated
date
user_id
number
group_id
number
name
string
desc
string
media_type
string
size
number
parent_dir_id
number

Example Response

{
 "id": 12,
 "object": "file",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "name": "",
 "desc": "",
 "media_type": "",
 "size": 12,
 "parent_dir_id": 12,
}

The Group Object

The group object.

Response Attributes
id
number

Unique ID of the group object.
object
string

group.
created
date
updated
date
title
string

Group title.
name
string

Group name.
nice_group_name
string

Nice version of the group name.
alias
string

Alias.
desc
string

Group description, in HTML.
plain_desc
string

Plain text version of the description.
subject_tag
string

Prepended to subject lines.
footer
string

Appended to group messages.
website
string

URL of associated website.
announce
boolean
moderated
boolean
new_users_moderated
boolean
unmoderate_users_after
number

Unmoderate users after N consecutive approved posts.
restricted
boolean
allow_non_subs_to_post
boolean
force_html_emails
boolean
normalize_html_emails
boolean

strip all font/colors/bg stuff from messages.
reply_to
string

Can be one of: group_reply_only_to_sender, group_reply_to_group, group_reply_to_group_and_sender, group_reply_to_moderators, group_reply_to_sender.
remove_other_reply_options
boolean
privacy
string

Can be one of: group_privacy_archives, group_privacy_none, group_privacy_unlisted, group_privacy_unlisted_public, sub_group_privacy_unlisted_public_archives.
seperate_footers
boolean

Place message footers in separate mime part.
allow_downloads
string

If we let members download archives. Can be one of: allow_downloads_by_members, allow_downloads_no.
members_visible
string

Can be one of: group_view_members_moderators, group_view_members_owners, group_view_members_subs.
subgroup_access
string

Who can create subgroups. Can be one of: sub_group_moderators, sub_group_owners, sub_group_subs.
calendar_access
string

Access control for the calendar. Can be one of: group_access_limited, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited, group_access_subscribers.
files_access
string

Access control for the files section. Can be one of: group_access_limited, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited, group_access_subscribers.
database_access
string

Access control for the database section. Can be one of: group_access_limited, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited, group_access_subscribers.
wiki_access
string

Access control for the wiki section. Can be one of: group_access_limited, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited, group_access_subscribers.
photos_access
string

Access control for the photo section. Can be one of: group_access_limited, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited, group_access_subscribers.
member_directory_access
string

Access control for the member directory section. Can be one of: group_access_limited, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited, group_access_subscribers.
polls_access
string

Access control for the polls section. Can be one of: polls_access_limited, polls_access_none, polls_access_subscribers.
chat_access
string

Access control for the chat section. Can be one of: group_access_limited, group_access_moderators_only, group_access_none, group_access_public, group_access_public_limited, group_access_subscribers.
handle_attachments
string

Can be one of: group_attachments_bounced, group_attachments_moderated, group_attachments_normal, group_attachments_stripped.
plain_text_only
boolean
handle_virus
string

How we handle messages that may have viruses. Can be one of: handle_virus_block, handle_virus_moderate.
locked
boolean

If the group is locked.
has_cover_photo
boolean
has_icon
boolean
parent_group_id
number
org_id
number
max_photo_size_email
string

If we resize photos in emails. Can be one of: max_photo_size_ex_small, max_photo_size_large, max_photo_size_medium, max_photo_size_medium_small, max_photo_size_none, max_photo_size_small, max_photo_size_somewhat_small.
max_photo_size_photos
string

If we resize photos uploaded to the photos section. Can be one of: max_photo_size_ex_small, max_photo_size_large, max_photo_size_medium, max_photo_size_medium_small, max_photo_size_none, max_photo_size_small, max_photo_size_somewhat_small.
max_photo_size_databases
string

If we resize photos uploaded to database tables. Can be one of: max_photo_size_ex_small, max_photo_size_large, max_photo_size_medium, max_photo_size_medium_small, max_photo_size_none, max_photo_size_small, max_photo_size_somewhat_small.
max_photo_size_wiki_images
string

If we resize photos uploaded to the wiki. Can be one of: max_photo_size_ex_small, max_photo_size_large, max_photo_size_medium, max_photo_size_medium_small, max_photo_size_none, max_photo_size_small, max_photo_size_somewhat_small.
hash_tags_required
boolean

whether messages must be tagged or not.
hash_tag_permissions
string

Can be one of: hash_tag_create_mods_bounce, hash_tag_create_mods_remove, hash_tag_create_subs.
bounce_attachments
boolean

If out of space, bounce messages with attachments instead of deleting old attachments.
allow_photos_in_files
boolean

Whether to allow photos in the Files section.
allow_reposts
boolean

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

The minimum number of days between reposts.
max_number_of_reposts
number

The maximum number of times a member can repost their message.
email_delivery_default
string

Default options for new subscriptions. Can be one of: email_delivery_digest, email_delivery_html_digest, email_delivery_none, email_delivery_single, email_delivery_special, email_delivery_summary.
message_selection_default
string

Can be one of: message_selection_all, message_selection_follow_and_first_message, message_selection_follow_only.
auto_follow_replies_default
boolean
max_attachment_size_default
string

Can be one of: max_attachment_size_large, max_attachment_size_medium, max_attachment_size_none, max_attachment_size_small, max_attachment_size_unlimited.
default_timezone
string
default_time_pref
string

Can be one of: military_time, standard_time.
default_date_pref
string

Can be one of: international_date, iso_date, us_date.
default_monday_start
boolean
disable_edits
boolean

Disable ability for members to edit messages.
disable_no_email
boolean

Disable ability for members to be set to No Email.
auto_close_threads
boolean

Automatically lock threads after a set number of days.
close_threads_after
number

unit is days.
auto_moderate_threads
boolean

Automatically moderate threads after a set number of days.
moderate_threads_after
number

unit is days.
subgroupcategoryid
number

ID of the subgroupcategory object this group belongs to, if any.
subs_count
number

Number of subscribers of the group, both normal and pending.
pending_subs_count
number

Number of pending subscribers, for restricted groups.
pending_msgs_count
number

Number of pending messages requiring approval.
open_chats_count
number

Number of open chats.
threads_count
number

Number of message threads in the archives.
messages_count
number

Number of messages in the archives.
org_domain
string
most_recent_message
date
cover_photo_url
string
icon_url
string
group_url
string
allow_parent_subs_to_post
boolean

If this is a subgroup, we can allow parent subscribers to post messages to it.
send_event_summaries
boolean

Send calendar event summary emails.
event_summary_schedule
string

Can be one of: event_summary_monthly, event_summary_weekly_friday.
perms
Perms object

If you are subscribed to the group, these are the permissions you have.
Methods That Use This Object
Create Group

View Method
Create Sub Group

View Method
Get Group Settings

View Method
Update Group

View Method

Example Response

{
 "id": 12,
 "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": 12,
 "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": 12,
 "org_id": 12,
 "max_photo_size_email": "max_photo_size_ex_small",
 "max_photo_size_photos": "max_photo_size_ex_small",
 "max_photo_size_databases": "max_photo_size_ex_small",
 "max_photo_size_wiki_images": "max_photo_size_ex_small",
 "hash_tags_required": false,
 "hash_tag_permissions": "hash_tag_create_mods_bounce",
 "bounce_attachments": false,
 "allow_photos_in_files": false,
 "allow_reposts": false,
 "min_days_between_reposts": 12,
 "max_number_of_reposts": 12,
 "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": 12,
 "auto_moderate_threads": false,
 "moderate_threads_after": 12,
 "subgroupcategoryid": 12,
 "subs_count": 12,
 "pending_subs_count": 12,
 "pending_msgs_count": 12,
 "open_chats_count": 12,
 "threads_count": 12,
 "messages_count": 12,
 "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,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
   },
}

The Group Alias Object

The group alias object.

Response Attributes
id
number
object
string

groupalias.
created
date
updated
date
name
string

Name.
alias_group_id
number

If not 0, this is not a real group, but an alias to another group.

Example Response

{
 "id": 12,
 "object": "groupalias",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "name": "example",
 "alias_group_id": 12,
}

The Group Alias List Object

/getgroupaliases return object.

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Group Alias objects
Methods That Use This Object
Get Group Aliases

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "groupalias",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "name": "example",
    "alias_group_id": 12,
   }
 ],
}

The Group List Object

/getsubgroups return object.

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Group objects
Methods That Use This Object
Get Sub Groups

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
      },
   }
 ],
}

The Hashtag Object

The hashtag object.

Response Attributes
id
number

Unique ID of the hashtag object.
object
string

hashtag.
created
date
group_id
number
name
string
mods_only_post
boolean
mods_only_replies
boolean
no_email
boolean
moderated
boolean
special
boolean
replies_unmoderated
boolean
locked
boolean
until
string

Can be one of: hash_tag_delete_day, hash_tag_delete_forever, hash_tag_delete_hour, hash_tag_delete_month, hash_tag_delete_week, hash_tag_delete_year.
close_instead_of_delete
boolean
description
string
color_name
string

Can be one of: tag_antique_pink, tag_apricot, tag_aquamute, tag_beige, tag_bluejean, tag_blush, tag_burnt_yellow, tag_capri_blue, tag_cerulean_blue, tag_cherry_blossom, tag_cloudy_blue, tag_cucumber, tag_dark_grey, tag_dark_orange, tag_dusty_mauve, tag_emerald_green, tag_grape, tag_green_lantern, tag_green_sage, tag_grey_blue, tag_light_brown, tag_light_grey, tag_light_lilac, tag_lilac, tag_lips, tag_melon, tag_military, tag_moss_green, tag_mulbery, tag_mustard, tag_orange, tag_orchid, tag_peony, tag_pink, tag_purple, tag_purple_blue, tag_purple_grey, tag_sage, tag_sky, tag_terracotta, tag_tomato, tag_yellow.
color_hex
string
reply_to
string

Can be one of: thread_reply_group_default, thread_reply_only_to_sender, thread_reply_to_group, thread_reply_to_group_and_sender, thread_reply_to_moderators, thread_reply_to_sender.
topic_count
number
last_message_date
date

Example Response

{
 "id": 12,
 "object": "hashtag",
 "created": "2009-11-10T15:00:00-08:00",
 "group_id": 12,
 "name": "",
 "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": 12,
 "last_message_date": "2009-11-10T15:00:00-08:00",
}

The Hashtag List Object

Hashtag List

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Hashtag objects
Methods That Use This Object
Get Hashtags

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "name": "",
    "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": 12,
    "last_message_date": "2009-11-10T15:00:00-08:00",
   }
 ],
}

The Login Object

The login object.

Response Attributes
token
string
user
User object
Methods That Use This Object
Login

View Method
Facebook Login Final

View Method
Google Login Final

View Method

Example Response

{
 "token": "aabbffed2213234",
 "user": 
   {
    "id": 12,
    "object": "user",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "email": "user@example.com",
    "full_name": "",
    "user_name": "",
    "timezone": "",
    "status": "user_status_bounced",
    "profile_photo_url": "",
    "post_pref": "",
    "per_page_pref": "",
    "allow_facebook_login": false,
    "allow_google_login": false,
    "allow_sso_login": false,
    "csrf_token": "",
    "two_factor_enabled": false,
    "recovery_codes": "",
    "dont_munge_message_id": false,
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "time_pref": "",
    "date_pref": "",
    "monday_start": false,
    "profile_privacy": "",
    "default_message_view": "expanded_message_view",
    "topics_sort_dir": "",
    "topic_sort_dir": "",
    "messages_sort_dir": "",
    "expanded_messages_sort_dir": "",
    "search_sort": "",
    "search_sort_dir": "",
    "photos_order_by": "",
    "photos_sort_dir": "",
    "album_order_by": "",
    "album_sort_dir": "",
    "home_page": "",
   },
}

The Member Info Object

The member object. This represents a subscription to a group.

Response Attributes
id
number

Unique ID of the member_info object.
object
string

member_info.
created
date
updated
date
user_id
number
group_id
number
group_name
string
status
string

Can be one of: sub_status_banned, sub_status_normal, sub_status_pending.
post_status
string

Can be one of: sub_poststatus_allowed, sub_poststatus_moderated, sub_poststatus_modfirstmessage, sub_poststatus_modstartedtopics, sub_poststatus_newusermoderated, sub_poststatus_normal, sub_poststatus_notallowed.
email_delivery
string

Can be one of: email_delivery_digest, email_delivery_html_digest, email_delivery_none, email_delivery_single, email_delivery_special, email_delivery_summary.
message_selection
string

Can be one of: message_selection_all, message_selection_follow_and_first_message, message_selection_follow_only.
auto_follow_replies
boolean
max_attachment_size
string

Can be one of: max_attachment_size_large, max_attachment_size_medium, max_attachment_size_none, max_attachment_size_small, max_attachment_size_unlimited.
approved_posts
number

For PostStatus == SUB_POSTSTATUS_NEWUSERMODERATED, count of consecutive approved posts. Used for Group.UnmoderateUsersAfter.
mod_status
string

Moderator data. Can be one of: sub_modstatus_moderator, sub_modstatus_none, sub_modstatus_owner.
pending_msg_notify
string

Can be one of: sub_notify_email, sub_notify_none.
pending_sub_notify
string

Can be one of: sub_notify_email, sub_notify_none.
sub_notify
string

Can be one of: sub_notify_email, sub_notify_none.
storage_notify
string

Can be one of: sub_notify_email, sub_notify_none.
sub_group_notify
string

Can be one of: sub_notify_email, sub_notify_none.
message_report_notify
string

Can be one of: sub_notify_email, sub_notify_none.
mod_permissions
string

Can be more than one of: sub_perm_banmembers, sub_perm_billing, sub_perm_createhashtags, sub_perm_editarchives, sub_perm_groupsettings, sub_perm_integrations, sub_perm_invitemembers, sub_perm_makemoderator, sub_perm_managepaidsubscriptions, sub_perm_managesubgroups, sub_perm_modsub, sub_perm_none, sub_perm_pendingmembers, sub_perm_pendingmsgs, sub_perm_removemembers, sub_perm_viewmembers.
owner_msg_notify
string

Can be one of: sub_ownermsg_notify_all, sub_ownermsg_notify_none, sub_ownermsg_notify_subs.
email
string
user_status
string

Can be one of: user_status_bounced, user_status_bouncing, user_status_confirmed, user_status_inactive, user_status_not_confirmed.
user_name
string
timezone
string
full_name
string
about_me
string
about_format
string
location
string
website
string
profile_photo_id
string

Empty if no profile photo.
profile_privacy
string

Can be one of: profile_members, profile_private, profile_public.
dont_munge_message_id
boolean
moderator_notes
string
moderator_notes_updated
date
use_signature
boolean
use_signature_email
boolean
Methods That Use This Object
Approve Pending Member

View Method
Ban Member

View Method
Bulk Remove Members

View Method
Get Member

View Method
Remove Member

View Method
Send A Bounce Probe

View Method
Send A Confirmation Email

View Method
Update Member

View Method
Get Subscription

View Method
Update Subscription

View Method

Example Response

{
 "id": 12,
 "object": "member_info",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "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": 12,
 "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": "",
 "full_name": "",
 "about_me": "",
 "about_format": "",
 "location": "",
 "website": "",
 "profile_photo_id": "",
 "profile_privacy": "profile_members",
 "dont_munge_message_id": false,
 "moderator_notes": "",
 "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
 "use_signature": false,
 "use_signature_email": false,
}

The Member Info List Object

The Member Info List object contains a list of Member Info objects.

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Member Info objects
Methods That Use This Object
Get Members

View Method
Search Members

View Method
Get Subscriptions

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   }
 ],
}

The Message Object

The message object.

Response Attributes
id
number
object
string

message.
created
date
updated
date
user_id
number
group_id
number
topic_id
number
body
string

body of the message to display, minus any quoted section at the end.
quoted
string

any quoted section at the end of the message.
remainder
string

for HTML messages, there may be a remainder part with just closing html tags.
snippet
string

Snippet, used for collapsed messages display.
subject
string

Subject of the message.
name
string
profile_photo_url
string

If not empty, use this URL to fetch the profile photo associated with the author of this message.
is_plain_text
boolean
msg_num
number
has_liked
boolean

If we've liked this message.
num_likes
number

Number of likes, not including our own.
is_closed
boolean

If the thread this message is a part of is closed.
is_moderated
boolean

If the thread this message is a part of is moderated.
reply_to
string

ReplyTo for this message (normally Group.ReplyTo unless modified by a tag). Can be one of: group_reply_only_to_sender, group_reply_to_group, group_reply_to_group_and_sender, group_reply_to_moderators, group_reply_to_sender.
can_repost
boolean

if we can repost this message.
hashtags
array of Hashtag objects

Example Response

{
 "id": 12,
 "object": "message",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "topic_id": 12,
 "body": "",
 "quoted": "",
 "remainder": "",
 "snippet": "",
 "subject": "",
 "name": "",
 "profile_photo_url": "",
 "is_plain_text": false,
 "msg_num": 12,
 "has_liked": false,
 "num_likes": 12,
 "is_closed": false,
 "is_moderated": false,
 "reply_to": "group_reply_only_to_sender",
 "can_repost": false,
 "hashtags": [
   {
    "id": 12,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "name": "",
    "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": 12,
    "last_message_date": "2009-11-10T15:00:00-08:00",
   }
 ],
}

The Message List Object

Message List

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
group_perms
Perms object
group
Group object
cover_photo_url
string
sub_data
array of Member Info objects
topic
Topic object
data
array of Message objects
Methods That Use This Object
Get Topic

View Method
Get Messages

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "group_perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
   },
 "group": 
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
      },
   },
 "cover_photo_url": "",
 "sub_data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   }
 ],
 "topic": 
   {
    "id": 12,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 12,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   },
 "data": [
   {
    "id": 12,
    "object": "message",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "topic_id": 12,
    "body": "",
    "quoted": "",
    "remainder": "",
    "snippet": "",
    "subject": "",
    "name": "",
    "profile_photo_url": "",
    "is_plain_text": false,
    "msg_num": 12,
    "has_liked": false,
    "num_likes": 12,
    "is_closed": false,
    "is_moderated": false,
    "reply_to": "group_reply_only_to_sender",
    "can_repost": false,
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}

The Oauth Login Object

The Oauth Login object.

Response Attributes
object
string

oauth_login.
state
string
web_client_id
string

Client ID needed for web applications.
ios_client_id
string

Client ID needed for IOS applications.
android_client_id
string

Client ID needed for Android applications.
scopes
array of string
Methods That Use This Object
Facebook Login Start

View Method
Google Login Start

View Method

Example Response

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

The Pagination Object

The pagination object is returned with every API response that takes pagination parameters.

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
}

The Past Member Object

The Past Member object contains the information associated with a member subscription that no longer exists. Because a member may be removed from multiple groups at once, the Past Member object may contain multiple member_info objects.

Response Attributes
id
number
object
string

past_member.
created
date

The time that this record was created.
action
string

The reason for the unsubscription. Can be one of: accepted_invitation, added_album, added_alias, added_dir, added_emailintegration, added_event, added_facebookintegration, added_file, added_githubintegration, added_hashtag, added_instagramintegration, added_member, added_photo, added_repeatevent, added_row, added_rssintegration, added_table, added_trellointegration, added_wikiimage, added_wikipage, applied, approved_member, approved_pending_message, attempted_banned_domain_post, attempted_banned_domain_registration, attempted_file_add_with_virus, attemptsub_bannedmember, bad_expired_thread, banned_member, bounced_user, changed_payer, changed_subscription_plan, changed_thread_replyto, changedemail, changedfullname, changedusername, closed_thread, created_group, created_subgroup, deleted_album, deleted_alias, deleted_attachment, deleted_dir, deleted_event, deleted_file, deleted_message, deleted_messageedit, deleted_pending_message, deleted_photo, deleted_repeatevent, deleted_row, deleted_subgroup, deleted_table, deleted_thread, deleted_wikiimage, deleted_wikipage, deleted_wikirev, deletedfollowing_repeatevent, delivery_changed, donation_closed, donation_reopened, donation_requested, donation_updated, edited_album, edited_emailintegration, edited_facebookintegration, edited_githubintegration, edited_group, edited_groupmessages, edited_hashtag, edited_instagramintegration, edited_message, edited_message_nosend, edited_moderator_note, edited_photo, edited_rssintegration, edited_trellointegration, event_rsvp_maybe, event_rsvp_no, event_rsvp_yes, expired_thread, exported_group, invited_member, joined, left, member_donated, member_donation_failed, merge_threads, modchangedemail, modchangedfullname, moderated_thread, moderator_changed, modified_dir, modified_event, modified_file, modified_repeatevent, modified_row, modified_table, modified_wikipage, moved_dir, moved_file, plan_change, poststatus_changed, reinvited_member, rejected_member, rejected_pending_message, removed_emailintegration, removed_facebookintegration, removed_githubintegration, removed_hashtag, removed_instagramintegration, removed_invite, removed_member, removed_rssintegration, removed_trellointegration, reopened_thread, resent_confirmation, resent_pending_membernotice, resumed_membership, rotated_photo, sent_bounce_probe, sent_message_accepted, sent_message_announcement, sent_message_announcementpassword, sent_message_attachmentbounced, sent_message_banned, sent_message_bouncedsub, sent_message_cantaddevent, sent_message_cantcreatetags, sent_message_closedtopic, sent_message_moderated, sent_message_modonlytags, sent_message_notags, sent_message_notallowed, sent_message_notconfirmedsub, sent_message_notsubscriber, sent_message_pendingsub, sent_message_toobig, sent_toowner, spamleft, split_thread, sticky_thread, stripe_account_connected, stripe_account_disconnected, unbanned_member, unbounced_user, unmoderated_thread, unsticky_thread, virus_bounced_member, virus_bounced_nonmember, virus_moderated.
member_info
Member Info object

Example Response

{
 "id": 12,
 "object": "past_member",
 "created": "2009-11-10T15:00:00-08:00",
 "action": "spamleft",
 "member_info": 
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   },
}

The Past Member List Object

The Past Member List object contains a list of Past Member objects.

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
data
array of Past Member objects
Methods That Use This Object
Get Past Members

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "data": [
   {
    "id": 12,
    "object": "past_member",
    "created": "2009-11-10T15:00:00-08:00",
    "action": "spamleft",
    "member_info": 
      {
       "id": 12,
       "object": "member_info",
       "created": "2009-11-10T15:00:00-08:00",
       "updated": "2009-11-10T15:00:00-08:00",
       "user_id": 12,
       "group_id": 12,
       "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": 12,
       "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": "",
       "full_name": "",
       "about_me": "",
       "about_format": "",
       "location": "",
       "website": "",
       "profile_photo_id": "",
       "profile_privacy": "profile_members",
       "dont_munge_message_id": false,
       "moderator_notes": "",
       "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
       "use_signature": false,
       "use_signature_email": false,
      },
   }
 ],
}

The Perms Object

Perms lists all possible Groups.io permissions, and which ones a particular subscription has.

Response Attributes
object
string

perms.
manage_subgroups
boolean

Does the user have permission to create and manage subgroups.
delete_group
boolean

Does the user have permission to delete the group.
view_archives
boolean

Does the user have permission to view group archives.
download_archives
boolean

Does the user have permission to download the group message archives.
download_entire_group
boolean

Does the user have permission to download all aspects of the group.
download_members
boolean

Does the user have permission to download the member list.
view_activity
boolean

Does the user have permission to view the activity log.
manage_hashtags
boolean

Does the user have permission to create and edit hashtags.
manage_integrations
boolean

Does the user have permission to manage group integrations, including Github, Trello, Facebook, RSS and Email integrations.
manage_group_settings
boolean

Does the user have permission to change group settings, including member notices and cover photos.
make_moderator
boolean

Does the user have permission to make another member a moderator.
manage_member_subscription_options
boolean

Does the user have permission to change other members' subscription options.
manage_pending_members
boolean

Does the user have permission to manage pending member subscriptions.
remove_members
boolean

Does the user have permission to remove members from the group.
ban_members
boolean

Does the user have permission to ban members from the group.
manage_group_billing
boolean

Does the user have permission to make changes to group billing, including upgrading the group, paying for the upgrade, and viewing invoices.
manage_group_payments
boolean

Does the user have permission to manage group payments, including setting up donations.
edit_archives
boolean

Does the user have permission to edit group messages, including merging topics.
manage_pending_messages
boolean

Does the user have permission to approve, deny and reject pending messages.
invite_members
boolean

Does the user have permission to invite people to join the group, and for premium groups, to directly add people to the group.
view_databases
boolean

Does the user have permission to edit databases.
can_post
boolean

Does the user have permission to post messages to the group.
can_vote
boolean

Does the user have permission to vote on polls.
manage_polls
boolean

Does the user have permission to add or edit polls. The user must have posting privileges, otherwise this will be false.
view_photos
boolean

Does the user have permission to view photo albums.
manage_photos
boolean

Does the user have permission to create photo albums and upload photos.
manage_members
boolean
view_calendar
boolean

done.
manage_calendar
boolean
view_chats
boolean

done.
manage_chats
boolean
view_member_directory
boolean

done.
view_files
boolean

done.
manage_files
boolean
view_members
boolean

done.
view_wiki
boolean

done.
manage_wiki
boolean
manage_subscription
boolean
view_guidelines
boolean
public_page
boolean
sub_page
boolean
mod_page
boolean
archives_visible
boolean

Whether specific functions should be visible. Separate from permissions.
members_visible
boolean
polls_visible
boolean
chat_visible
boolean
calendar_visible
boolean
files_visible
boolean
database_visible
boolean
photos_visible
boolean
wiki_visible
boolean
member_directory_visible
boolean
Methods That Use This Object
Get Permissions

View Method

Example Response

{
 "object": "perms",
 "manage_subgroups": false,
 "delete_group": false,
 "view_archives": 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,
 "view_guidelines": false,
 "public_page": false,
 "sub_page": false,
 "mod_page": false,
 "archives_visible": false,
 "members_visible": false,
 "polls_visible": false,
 "chat_visible": false,
 "calendar_visible": false,
 "files_visible": false,
 "database_visible": false,
 "photos_visible": false,
 "wiki_visible": false,
 "member_directory_visible": false,
}

The Photo Object

The file object.

Response Attributes
id
number

Unique ID of the photo object.
object
string

photo.
created
date
updated
date
user_id
number
group_id
number
name
string
desc
string
media_type
string
size
number
column

width - number:
column

height - number:
column

album_id - number:
format
string

Type of image (jpeg, gif, png).
focal_length
number

Focal Length, in mm.
iso
number

ISO.
aperture
number

Aperture, as in f/aperture.
shutter_speed
number

Shutter speed, in 1/shutterspeed seconds.
taken
number

Time Taken, in Unix seconds since epoch.
make
string

Camera make and model.
model
string
column

gallery_url - string:

Example Response

{
 "id": 12,
 "object": "photo",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "name": "",
 "desc": "",
 "media_type": "",
 "size": 12,
 "column:width": 12,
 "column:height": 12,
 "column:album_id": 12,
 "format": "",
 "focal_length": 3.2,
 "iso": 12,
 "aperture": 3.2,
 "shutter_speed": 12,
 "taken": 12,
 "make": "",
 "model": "",
 "column:gallery_url": "",
}

The RSVP Object

The rsvp object.

Response Attributes
id
number

Unique ID of the rsvp object.
object
string

rsvp.
created
date

The time that this object was created.
updated
date

The time that this object was last updated.
event_id
number

The ID of the associated event object.
group_id
number

The ID of the associated group.
user_id
number

The ID of the person who created this rsvp.
user_name
string

The user_name of the person who created this rsvp.
full_name
string

The full_name of the person who created this rsvp.
email
string

The email address of the person who created this rsvp.
profile_photo_id
string
type
string

The type of RSVP. Can be one of: rsvp_maybe, rsvp_no, rsvp_waitlist, rsvp_yes.
comment
string

Some events ask a question of people rsvp'ing. This is that answer.
additional_guests
number

Some events allow additional guests.
Methods That Use This Object
RSVP To An Event

View Method

Example Response

{
 "id": 12,
 "object": "rsvp",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "event_id": 12,
 "group_id": 12,
 "user_id": 12,
 "user_name": "",
 "full_name": "",
 "email": "",
 "profile_photo_id": "",
 "type": "rsvp_maybe",
 "comment": "",
 "additional_guests": 12,
}

The Success Object

The success object.

Response Attributes
object
string

success.
extra
string

Example Response

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

The Topic Object

The topic object.

Response Attributes
id
number
object
string

topic.
created
date
updated
date
group_id
number
group_subject_tag
string
subject
string

Subject of the topic.
summary
string

Summary of the first message in the topic.
name
string

Name of the originator of the topic.
profile_photo_url
string

If not empty then there is a profile photo associated with this author.
num_messages
number

Number of messages in the topic.
is_sticky
boolean

If the topic is sticky.
is_moderated
boolean

If the topic is moderated.
is_closed
boolean

If the topic is closed.
has_attachments
boolean

If the topic has at least one message that has attachments.
reply_to
string

Can be one of: thread_reply_group_default, thread_reply_only_to_sender, thread_reply_to_group, thread_reply_to_group_and_sender, thread_reply_to_moderators, thread_reply_to_sender.
most_recent_message
date

Date of the most recent message in the topic.
hashtags
array of Hashtag objects

Example Response

{
 "id": 12,
 "object": "topic",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "group_id": 12,
 "group_subject_tag": "",
 "subject": "",
 "summary": "",
 "name": "",
 "profile_photo_url": "",
 "num_messages": 12,
 "is_sticky": false,
 "is_moderated": false,
 "is_closed": false,
 "has_attachments": false,
 "reply_to": "thread_reply_group_default",
 "most_recent_message": "2009-11-10T15:00:00-08:00",
 "hashtags": [
   {
    "id": 12,
    "object": "hashtag",
    "created": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "name": "",
    "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": 12,
    "last_message_date": "2009-11-10T15:00:00-08:00",
   }
 ],
}

The Topic List Object

Topic List

Response Attributes
object
string

list.
total_count
number

The total number of items available.
start_item
number

The index of the first item, from 0.
end_item
number

The index of the last item, from 0.
has_more
boolean

Whether there are more items available.
next_page_token
number

An opaque token that is to be returned to fetch the next set of objects.
group_perms
Perms object
group
Group object
sub_data
array of Member Info objects
data
array of Topic objects
Methods That Use This Object
Get Topics

View Method

Example Response

{
 "object": "list",
 "total_count": 12,
 "start_item": 12,
 "end_item": 12,
 "has_more": false,
 "next_page_token": 12,
 "group_perms": 
   {
    "object": "perms",
    "manage_subgroups": false,
    "delete_group": false,
    "view_archives": 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,
    "view_guidelines": false,
    "public_page": false,
    "sub_page": false,
    "mod_page": false,
    "archives_visible": false,
    "members_visible": false,
    "polls_visible": false,
    "chat_visible": false,
    "calendar_visible": false,
    "files_visible": false,
    "database_visible": false,
    "photos_visible": false,
    "wiki_visible": false,
    "member_directory_visible": false,
   },
 "group": 
   {
    "id": 12,
    "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": 12,
    "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": 12,
    "org_id": 12,
    "max_photo_size_email": "max_photo_size_ex_small",
    "max_photo_size_photos": "max_photo_size_ex_small",
    "max_photo_size_databases": "max_photo_size_ex_small",
    "max_photo_size_wiki_images": "max_photo_size_ex_small",
    "hash_tags_required": false,
    "hash_tag_permissions": "hash_tag_create_mods_bounce",
    "bounce_attachments": false,
    "allow_photos_in_files": false,
    "allow_reposts": false,
    "min_days_between_reposts": 12,
    "max_number_of_reposts": 12,
    "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": 12,
    "auto_moderate_threads": false,
    "moderate_threads_after": 12,
    "subgroupcategoryid": 12,
    "subs_count": 12,
    "pending_subs_count": 12,
    "pending_msgs_count": 12,
    "open_chats_count": 12,
    "threads_count": 12,
    "messages_count": 12,
    "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,
       "view_archives": 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,
       "view_guidelines": false,
       "public_page": false,
       "sub_page": false,
       "mod_page": false,
       "archives_visible": false,
       "members_visible": false,
       "polls_visible": false,
       "chat_visible": false,
       "calendar_visible": false,
       "files_visible": false,
       "database_visible": false,
       "photos_visible": false,
       "wiki_visible": false,
       "member_directory_visible": false,
      },
   },
 "sub_data": [
   {
    "id": 12,
    "object": "member_info",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "user_id": 12,
    "group_id": 12,
    "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": 12,
    "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": "",
    "full_name": "",
    "about_me": "",
    "about_format": "",
    "location": "",
    "website": "",
    "profile_photo_id": "",
    "profile_privacy": "profile_members",
    "dont_munge_message_id": false,
    "moderator_notes": "",
    "moderator_notes_updated": "2009-11-10T15:00:00-08:00",
    "use_signature": false,
    "use_signature_email": false,
   }
 ],
 "data": [
   {
    "id": 12,
    "object": "topic",
    "created": "2009-11-10T15:00:00-08:00",
    "updated": "2009-11-10T15:00:00-08:00",
    "group_id": 12,
    "group_subject_tag": "",
    "subject": "",
    "summary": "",
    "name": "",
    "profile_photo_url": "",
    "num_messages": 12,
    "is_sticky": false,
    "is_moderated": false,
    "is_closed": false,
    "has_attachments": false,
    "reply_to": "thread_reply_group_default",
    "most_recent_message": "2009-11-10T15:00:00-08:00",
    "hashtags": [
      {
       "id": 12,
       "object": "hashtag",
       "created": "2009-11-10T15:00:00-08:00",
       "group_id": 12,
       "name": "",
       "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": 12,
       "last_message_date": "2009-11-10T15:00:00-08:00",
      }
    ],
   }
 ],
}

The User Object

The user object.

Response Attributes
id
number
object
string

user.
created
date
updated
date
email
string
full_name
string
user_name
string
timezone
string
status
string

Can be one of: user_status_bounced, user_status_bouncing, user_status_confirmed, user_status_inactive, user_status_not_confirmed.
profile_photo_url
string
post_pref
string
per_page_pref
string
allow_facebook_login
boolean
allow_google_login
boolean
allow_sso_login
boolean
csrf_token
string
two_factor_enabled
boolean
recovery_codes
string
dont_munge_message_id
boolean

If true, we do not replace the message-id on any messages you send to groups. Replacing the message-id is a way to force Gmail (and others) to display messages you send.
about_me
string

Profile stuff.
about_format
string
location
string
website
string
time_pref
string
date_pref
string
monday_start
boolean
profile_privacy
string

Who can see this profile.
default_message_view
string

The view we go into when viewing messages. Can be one of: expanded_message_view, message_view, polls_view, thread_view.
topics_sort_dir
string

Sort direction in threads view.
topic_sort_dir
string

Sort direction when viewing an individual thread.
messages_sort_dir
string

Sort direction in messages view.
expanded_messages_sort_dir
string

Sort direction in expanded messages view.
search_sort
string

SearchSort is the default sort of search results.
search_sort_dir
string

Sort direction in search results (does not apply to RelevanceSort).
photos_order_by
string

Sort direction in photos view (albums).
photos_sort_dir
string
album_order_by
string

Sort direction in photo album view.
album_sort_dir
string
home_page
string

Which home page to display.
Methods That Use This Object
Get User

View Method
Update User

View Method

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

The Wiki Object

The file object.

Response Attributes
id
number
object
string

wiki.
created
date
updated
date
user_id
number
group_id
number
title
string
desc
string
format
string
locked
boolean
rev_count
number

Example Response

{
 "id": 12,
 "object": "wiki",
 "created": "2009-11-10T15:00:00-08:00",
 "updated": "2009-11-10T15:00:00-08:00",
 "user_id": 12,
 "group_id": 12,
 "title": "",
 "desc": "",
 "format": "",
 "locked": false,
 "rev_count": 12,
}