Groups.io API Reference

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.

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

API Endpoint

api.groups.io

Versioning And Change Log

When we make backwards-incompatible changes to the API, we release new, dated versions.

View the changelog to see changes between different versions.

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

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

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

Errors

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

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

Response Attributes

object string, value is "error"	String representing the object’s type. Objects of the same type share the same value.
type	The type of error returned.
extra	Extra information, error specific.

General Errors

unauthorized	Incorrect email address or password.
bad_request	Incorrect parameters passed in. For example, a group id that doesn't exist.
authentication	Failure to properly authenticate yourself in the request.
expired	The supplied authentication token is too old.
rate_limit	Too many requests hit the API too quickly.
inadequate_permissions	You do not have permission to execute the specific API call.
invalid_value	When a value is unrecognized. The `extra` field will be set to the name of the field with the invalid value.
server	There was a problem with the server. Please try again later.

HTTP status code summary

200 OK	Everything worked as expected.
400 Bad Request	The request was unacceptable, often due to missing a required parameter.
429 Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

Example Error Response

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

Pagination

Some API resources support pagination. These calls take at least these query parameters: limit, page_token, sort_field, sort_dir. Their responses use the list response format defined below.

Groups.io utilizes cursor-based pagination via the page_token and next_page_token parameters. For the first call to an endpoint that supports paging, do not include the page_token parameter. The response will include a next_page_token number. To fetch the next page of results, call the endpoint with page_token set to the next_page_token number.

Query Parameters

limit optional number, 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. Valid values are dependent on the call.
sort_dir optional string	Sort direction. Can be 'asc' or 'desc'.

List Response Format

object string, value is "list"	String representing the object’s type. Objects of the same type share the same value.
total_count number	The total number of items.
start_item number	The index of the first item returned.
end_item number	The index of the last item returned.
has_more boolean	Whether or not there are more elements available after this set. If `false`, this set comprises the end of the list.
next_page_token opaque	To fetch the next page, set the `page_token` value to this number. This should be considered an opaque value.
data array	An array containing the actual response elements, paginated by any request parameters.

Example Response

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

Libraries

The following are unofficial libraries.

JAVA	github.com/lake54/groupsio-api-java

Authentication to the API is performed via HTTP Basic Auth, using a token received from the login API call. For all API calls that require authentication, provide the token as the basic auth username value.

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

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

Login

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

Query Parameters

email required string	The email address of the user.
password required string	The password of the user.
domain optional string	The domain to log in under. If not specified, `groups.io` is assumed.
twofactor optional number	If the user account is configured to require two factor authentication, the second factor from an Authenticator app.

Returns

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

Successful Response Attributes

token string	String representing the authentication token.
name string	Name of the user, if there is one.

Additional Errors

2nd_factor_required	The account has two factor enabled and the twofactor parameter was not specified.
2nd_factor_wrong	The the second factor is incorrect.
email	The email address is missing or incorrect.
password	The password is missing or incorrect.
domain	The domain is not recognized.
api_key	The API Key is missing or incorrect.

Definition

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

Example Request

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

Example Successful Response

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

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 Bulk Remove Results Object

Response Attributes

object string, read-only, value is "bulk_remove_results"	String representing the object’s type. Objects of the same type share the same value.
total_emails number	The total number of email addresses submitted for bulk removal.
removed number	The number of email addressess successfully removed.
errors array	An array of `remove_error` objects
object string, read-only, value is "remove_error"	String representing the object’s type. Objects of the same type share the same value.
email string	The email address that had an error.
status string	The reason for the error, can be: `bulk_remove_db_error`, `bulk_remove_not_a_member`, `bulk_remove_sole_group_owner`.

Example Response

  {
    "object": "bulk_remove_results",
    "errors": [
      {
        "object": "remove_error",
        "email": "test@example.com",
        "status": "bulk_remove_not_a_member"
      },
      {
        "object": "remove_error",
        "email": "john@smith.com",
        "status": "bulk_remove_sole_group_owner"
      }
    ],
    "total_emails": 3,
    "removed": 1
  }

The Direct Add Results Object

Response Attributes

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

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

total_emails
number

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

added_subs
array

An array of subscription objects representing the successful adds.

errors
array

An array of direct_add_error objects

Attributes for errors object

object string, read-only, value is "direct_add_error"	String representing the object’s type. Objects of the same type share the same value.
email string	The email address that had an error.
status string	The reason for the error, can be: `direct_add_db_error`, `direct_add_invalid_email`, `direct_add_existing`, `direct_add_pending`, `direct_add_banned`, `direct_add_inactive`.
group_id int	The ID of the group this error pertains to.

Example Response

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

The Group Object

Response Attributes

id int, read-only
object string, read-only, value is "user"	String representing the object’s type. Objects of the same type share the same value.
created date, read-only	Created date
updated date, read-only	Last updated date
title string
name string
alias string
desc string
subject_tag string
footer string
website string
announce boolean
moderated boolean
new_users_moderated boolean
unmoderate_users_after number
restricted boolean
allow_non_subs_to_post boolean
force_html_emails boolean
normalize_html_emails boolean
reply_to string	Can be: `group_reply_to_group`, `group_reply_to_sender`, `group_reply_to_moderators`, `group_reply_to_group_and_sender`
remove_other_reply_options boolean
privacy string	Can be: `group_privacy_none`, `group_privacy_archives`, `group_privacy_unlisted`, `group_privacy_unlisted_public`
members_visible string	Can be: `group_view_members_subs`, `group_view_members_moderators`, `group_view_members_owners`
subgroup_access string	Can be: `sub_group_subs`, `sub_group_moderators`, `sub_group_owners`
calendar_access string	Access, can be: `group_access_limited`, `group_access_subscribers`, `group_access_moderators_only`, `group_access_none`, `group_access_public`, `group_access_public_limited`
files_access string	Access, can be: `group_access_limited`, `group_access_subscribers`, `group_access_moderators_only`, `group_access_none`
database_access string	Access, can be: `group_access_limited`, `group_access_subscribers`, `group_access_moderators_only`, `group_access_none`
wiki_access string	Access, can be: `group_access_limited`, `group_access_subscribers`, `group_access_moderators_only`, `group_access_none`, `group_access_public`, `group_access_public_limited`
photos_access string	Access, can be: `group_access_limited`, `group_access_subscribers`, `group_access_moderators_only`, `group_access_none`
member_directory_access string	Access, can be: `group_access_limited`, `group_access_moderators_only`, `group_access_none`
polls_access string	Access, can be: `group_access_limited`, `group_access_subscribers`, `group_access_moderators_only`, `group_access_none`, `group_access_public`, `group_access_public_limited`
chat_access string	Access, can be: `group_access_limited`, `group_access_subscribers`, `group_access_none`
handle_attachments string	Can be: `group_attachments_normal`, `group_attachments_bounced`, `group_attachments_stripped`, `group_attachments_moderated`
handle_virus string	Can be: `handle_virus_block`, `handle_virus_moderate`
plain_text_only boolean
fig_leaf string	Can be `fig_leaf_archives`, `fig_leaf_none`
max_photo_size_email string	Can be: `max_photo_size_none`, `max_photo_size_small`, `max_photo_size_medium`, `max_photo_size_large`, `max_photo_size_ex_small`, `max_photo_size_medium_small`, `max_photo_size_somewhat_small`
max_photo_size_photos string	Can be: `max_photo_size_none`, `max_photo_size_small`, `max_photo_size_medium`, `max_photo_size_large`, `max_photo_size_ex_small`, `max_photo_size_medium_small`, `max_photo_size_somewhat_small`
max_photo_size_databases string	Can be: `max_photo_size_none`, `max_photo_size_small`, `max_photo_size_medium`, `max_photo_size_large`, `max_photo_size_ex_small`, `max_photo_size_medium_small`, `max_photo_size_somewhat_small`
max_photo_size_wiki_images string	Can be: `max_photo_size_none`, `max_photo_size_small`, `max_photo_size_medium`, `max_photo_size_large`, `max_photo_size_ex_small`, `max_photo_size_medium_small`, `max_photo_size_somewhat_small`
hash_tags_required boolean
hash_tag_permissions string	Can be: `hash_tag_create_subs`, `hash_tag_create_mods_bounce`, `hash_tag_create_mods_remove`
bounce_attachments boolean
allow_photos_in_files boolean
email_delivery_default string	Email delivery, can be `email_delivery_single`, `email_delivery_digest`, `email_delivery_special`, `email_delivery_none`, `email_delivery_html_digest`, `email_delivery_summary`
message_selection_default string	Message selection, can be `message_selection_all`, `message_selection_follow_only`, `message_selection_follow_and_first_message`
auto_follow_replies_default boolean
max_attachment_size_default string	Maximum attachment size, can be `max_attachment_size_unlimited`, `max_attachment_size_small`, `max_attachment_size_medium`, `max_attachment_size_large`, `max_attachment_size_none`
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.
default_time_pref optional string	Default preference for how to display times, `standard_time`, `military_time`
default_date_pref optional string	Default preference for how to display dates, `us_date`, `iso_date`, `international_date`
allow_downloads string	Can be `allow_downloads_no`, `allow_downloads_by_members`.
seperate_footers boolean
disable_edits boolean
disable_no_email boolean
auto_close_threads boolean
close_threads_after number
auto_moderate_threads boolean
moderate_threads_after number
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.
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.
subgroupcategoryid number	ID of the subgroupcategory object this group belongs to, if any.

Example Response

{
  "id": 5,
  "object": "group",
  "created": "2017-08-03T10:18:15.218974479-07:00",
  "updated": "2017-08-15T12:48:41.965409169-07:00",
  "title": "",
  "parent_group_id": 0,
  "name": "test",
  "alias": "main",
  "desc": "This is a description of a test group.",
  "subject_tag": "[test]",
  "footer": "This is my\r\nFooter!!!!",
  "website": "",
  "announce": false,
  "moderated": false,
  "new_users_moderated": true,
  "unmoderate_users_after": 1,
  "restricted": false,
  "allow_non_subs_to_post": false,
  "force_html_emails": false,
  "normalize_html_emails": false,
  "reply_to": "group_reply_to_group",
  "remove_other_reply_options": false,
  "privacy": "group_privacy_none",
  "members_visible": "group_view_members_subs",
  "subgroup_access": "sub_group_subs",
  "calendar_access": "group_access_limited",
  "files_access": "group_access_limited",
  "database_access": "group_access_limited",
  "wiki_access": "group_access_limited",
  "photos_access": "group_access_limited",
  "member_directory_access": "group_access_limited",
  "polls_access": "polls_access_subscribers",
  "chat_access": "group_access_limited",
  "handle_attachments": "group_attachments_normal",
  "handle_virus": "handle_virus_block",
  "plain_text_only": false,
  "fig_leaf": "fig_leaf_archives",
  "max_photo_size_email": "max_photo_size_none",
  "max_photo_size_photos": "max_photo_size_none",
  "max_photo_size_databases": "max_photo_size_none",
  "max_photo_size_wiki_images": "max_photo_size_none",
  "hash_tags_required": false,
  "hash_tag_permissions": "hash_tag_create_subs",
  "bounce_attachments": false,
  "allow_photos_in_files": false,
  "email_delivery_default": "email_delivery_none",
  "message_selection_default": "message_selection_all",
  "auto_follow_replies_default": true,
  "max_attachment_size_default": "max_attachment_size_unlimited",
  "default_timezone": "america/los_angeles",
  "allow_downloads": "allow_downloads_no",
  "seperate_footers": false,
  "subgroup_category_id": 0,
  "disable_edits": false,
  "disable_no_email": false,
  "auto_close_threads": false,
  "close_threads_after": 0,
  "auto_moderate_threads": false,
  "moderate_threads_after": 0,
  "allow_reposts": false,
  "min_days_between_reposts": 0,
  "max_number_of_reposts": 0,
  "subs_count": 10,
  "pending_subs_count": 0,
  "pending_msgs_count": 0,
  "open_chats_count": 0,
  "threads_count": 30,
  "messages_count": 82
}

The Hashtag Object

Response Attributes

id number	ID of the hashtag
name string	Name of the hashtag
color string	Hex color of the hashtag
group_id number	ID of the group
mods_only_post boolean
mods_only_replies boolean
no_email boolean
moderated boolean
special boolean
replies_unmoderated boolean
locked boolean
until string, one of
close_instead_of_delete boolean
description string
color_name string
color_hex string
reply_to string, one of
topic_count number
last_message_date date

Example Response

        {
          "id": 11,
          "object": "hashtag",
          "created": "2018-10-30T12:13:35.055905988-07:00",
          "group_id": 1,
          "name": "polls",
          "mods_only_post": false,
          "mods_only_replies": false,
          "no_email": false,
          "moderated": false,
          "special": false,
          "replies_unmoderated": false,
          "locked": false,
          "until": "hash_tag_delete_forever",
          "close_instead_of_delete": false,
          "description": "",
          "color_name": "tag_cerulean_blue",
          "color_hex": "#4191d6",
          "reply_to": "thread_reply_group_default",
          "topic_count": 1,
          "last_message_date": "2018-10-30T12:13:35.054086063-07:00"
        }

The Invite Results Object

Response Attributes

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

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

total_emails
number

The total number of email addresses submitted for the invite.

invited
array

An array of email addresses that have been successfully invited.

errors
array

An array of invite_error objects

Attributes for errors object

object string, read-only, value is "invite_error"	String representing the object’s type. Objects of the same type share the same value.
email string	The email address that had an error.
status string	The reason for the error, can be: `invite_db_error`, `invite_invalid_email`, `invite_existing`, `invite_pending`, `invite_banned`, `invite_inactive`, `invite_inactive`, `invite_normal`, `invite_not_confirmed`, `invite_bouncing`, `invite_reinvite`.

Example Response

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

The Permissions Object

Response Attributes

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

Example Response

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

The Subscription Object

Attributes

id number, read-only	Subscription ID
object string, read-only, value is "subscription"	String representing the object’s type. Objects of the same type share the same value.
created date, read-only	Created date
updated date, read-only	Last updated date
user_id number, read-only	User ID
group_id number, read-only	Group ID
status string	Subscription status, can be `sub_status_normal`, `sub_status_pending`, `sub_status_banned`
post_status string	Posting status, can be `sub_poststatus_normal`, `sub_poststatus_allowed`, `sub_poststatus_moderated`, `sub_poststatus_notallowed`, `sub_poststatus_newusermoderated`, `sub_poststatus_modfirstmessage`, `sub_poststatus_modstartedtopics`
email_delivery string	Email delivery, can be `email_delivery_single`, `email_delivery_digest`, `email_delivery_special`, `email_delivery_none`, `email_delivery_html_digest`, `email_delivery_summary`
message_selection string	Message selection, can be `message_selection_all`, `message_selection_follow_only`, `message_selection_follow_and_first_message`
auto_follow_replies boolean
max_attachment_size string	Maximum attachment size, can be `max_attachment_size_unlimited`, `max_attachment_size_small`, `max_attachment_size_medium`, `max_attachment_size_large`, `max_attachment_size_none`
approved_posts number, read-only
email string, read-only
user_status string, read-only	User status, can be `user_status_not_confirmed`, `user_status_confirmed`, `user_status_inactive`, `user_status_bouncing`, `user_status_bounced`
user_name string, read-only
timezone string, read-only
full_name string
about_me string
about_format string
location string
website string
profile_privacy string	Profile visibility, `profile_private`, `profile_members`, `profile_public`
dont_munge_message_id boolean, read-only	Whether to change the message-id of any posted messages
moderator_notes string	Free-form data. This will be empty if the object is 'subscription_plus'.
moderator_notes_updated date, read-only
use_signature boolean
use_signature_email boolean
The following is moderator data
mod_status string	Moderator status, can be `sub_modstatus_none`, `sub_modstatus_moderator`, `sub_modstatus_owner`
pending_msg_notify string	Notify about pending messages, can be `sub_notify_email`, `sub_notify_none`
pending_sub_notify string	Notify about pending subscriptions, can be `sub_notify_email`, `sub_notify_none`
sub_notify string	Notify when someone joins the group, can be `sub_notify_email`, `sub_notify_none`
storage_notify string	Notify when storage limits are reached, can be `sub_notify_email`, `sub_notify_none`
sub_group_notify string	Notify when a subgroup is created, can be `sub_notify_email`, `sub_notify_none`
message_report_notify string	Notify when someone reports a message, can be `sub_notify_email`, `sub_notify_none`
owner_msg_notify string	Receive messages sent to the +owner address, can be `sub_ownermsg_notify_all`, `sub_ownermsg_notify_subs`, `sub_ownermsg_notify_none`
mod_permissions string	Moderator permissions, comma separated list of zero or more ofthe following: `sub_perm_pendingmsgs`, `sub_perm_pendingmembers`, `sub_perm_invitemembers`, `sub_perm_removemembers`, `sub_perm_banmembers`, `sub_perm_makemoderator`, `sub_perm_createhashtags`, `sub_perm_groupsettings`, `sub_perm_modsub`, `sub_perm_integrations`, `sub_perm_editarchives`, `sub_perm_billing`, `sub_perm_managesubgroups`, `sub_perm_viewmembers`

Example Response

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

The Subscription Plus Object

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

Additional Attributes

num_subs number, read-only	Number of subscriptions in the associated group.
pending_messages number, read-only	Number of pending messages in the associated group.
pending_subs number, read-only	Number of pending subscriptions in the associated group.
most_recent_message date, read-only	Date of the most recent message.

Example Response

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

The Topic Object

Response Attributes

id
number

ID of the topic

group_id
number

ID of the group

subject
string

Subject of the topic

summary
string

Summary of the first message in the topic

poster
object

Poster of the first message in the topic

Attributes for poster object

name string	Name of the poster to be displayed
user_id number	ID of the poster (may be 0)
user_name string	User name of the post (may be empty)

num_messages
number

The number of messages in the topic

is_sticky
boolean

If the topic is sticky

is_moderated
boolean

If the topic is moderated

is_closed
boolean

If the topic is closed

reply_to
string, one of

most_recent_message
date

Date of the most recent message

hashtags
array

Array of hashtag objects

Example Response

    {
      "id": 1,
      "object": "topic",
      "created": "2014-09-29T23:39:41-07:00",
      "updated": "2018-10-30T12:12:02.050310598-07:00",
      "group_id": 1,
      "group_subject_tag": "[beta]",
      "subject": "Announcement in other moderator groups?",
      "summary": "Lorem ipsum consectetur sunt ea ad in dolore dolore deserunt magna ut labore anim proident.",
      "poster": {
        "name": "Poster name",
        "user_name": "",
        "user_id": 0
      },
      "num_messages": 4,
      "is_sticky": false,
      "is_moderated": false,
      "is_closed": false,
      "reply_to": "thread_reply_group_default",
      "most_recent_message": "2014-09-30T08:15:54-07:00",
      "hashtags": [
        {
          "id": 11,
          "object": "hashtag",
          "created": "2018-10-30T12:13:35.055905988-07:00",
          "group_id": 1,
          "name": "polls",
          "mods_only_post": false,
          "mods_only_replies": false,
          "no_email": false,
          "moderated": false,
          "special": false,
          "replies_unmoderated": false,
          "locked": false,
          "until": "hash_tag_delete_forever",
          "close_instead_of_delete": false,
          "description": "",
          "color_name": "tag_cerulean_blue",
          "color_hex": "#4191d6",
          "reply_to": "thread_reply_group_default",
          "topic_count": 1,
          "last_message_date": "2018-10-30T12:13:35.054086063-07:00"
        },
        {
          "id": 9,
          "object": "hashtag",
          "created": "2018-10-30T12:13:33.697439788-07:00",
          "group_id": 1,
          "name": "wishlist",
          "mods_only_post": false,
          "mods_only_replies": false,
          "no_email": false,
          "moderated": false,
          "special": false,
          "replies_unmoderated": false,
          "locked": false,
          "until": "hash_tag_delete_forever",
          "close_instead_of_delete": false,
          "description": "",
          "color_name": "tag_cerulean_blue",
          "color_hex": "#4191d6",
          "reply_to": "thread_reply_group_default",
          "topic_count": 4,
          "last_message_date": "2018-10-30T12:13:35.069679546-07:00"
        }
      ]
    }

The User Object

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

Attributes

id number, read-only	ID of the user
object string, read-only, value is "user"	String representing the object’s type. Objects of the same type share the same value.
created date, read-only	Date the user was created
updated date, read-only	Date the user was last updated
email string	Email address of the user
full_name string	Full name of the user
user_name string	User name of the user
timezone string	Timezone of the user
status string	User status, `user_status_not_confirmed`, `user_status_confirmed`, `user_status_inactive`, `user_status_bouncing`, `user_status_bounced`
has_profile_photo boolean	If the user has uploaded a photo
profile_photo_id number	The ID of the profile photo
post_pref string	Posting preference, `user_postpref_html`, `user_postpref_plain`, `user_postpref_markdown`
per_page_pref string	Per page display preference, `user_per_page_pref20`, `user_per_page_pref50`, `user_per_page_pref100`, `user_per_page_pref_infinite`
allow_facebook_login boolean	Whether login by Facebook is permitted
allow_google_login boolean	Whether login by Google is permitted
two_factor_enabled boolean, read-only	If 2Factor authentication is enabled
recovery_codes string, read-only	If 2Factor authentication is enabled, these are the recovery codes
dont_munge_message_id boolean	Whether to change the message-id of any posted messages
about_me string	Profile about me information
about_format string	Format of the about me, `about_html`, `about_plain`, `about_markdown`
location string	Profile location information
website string	Profile website
time_pref string	How to display times, `standard_time`, `military_time`
date_pref string	How to display dates, `us_date`, `iso_date`, `international_date`
profile_privacy string	Profile visibility, `profile_private`, `profile_members`, `profile_public`
default_message_view string	Which message view to display by default, `thread_view`, `message_view`, `expanded_message_view`, `polls_view`
topics_sort_dir string	Default sort direction of topics, `sort_none`, `sort_asc`, `sort_desc`
topic_sort_dir string	Default sort direction of an individual topic, `sort_none`, `sort_asc`, `sort_desc`
messages_sort_dir string	Default sort direction of the messages view, `sort_none`, `sort_asc`, `sort_desc`
expanded_messages_sort_dir string	Default sort direction of the expanded messages view, `sort_none`, `sort_asc`, `sort_desc`
search_sort string	Default sort type for searches, `relevance_sort`, `date_sort`
search_sort_dir string	Defualt sort direction of search, `sort_none`, `sort_asc`, `sort_desc`

Example Response

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

Actions involving the authenticated user.

Get User

Return the user information associated with an authentication token.

Definition

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

Example Request

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

Example Successful Response

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

Update User

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

POST Parameters

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
allow_facebook_login optional boolean
allow_google_login optional boolean

Returns

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

Additional Errors

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

Definition

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

Example Request

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

Example Successful Response

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

Example Error Response

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

Get Subscriptions

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

Query Parameters

limit optional default is 10	A limit on the number of objects to be returned, between 1 and 100.
page_token optional opaque	A cursor for use in pagination. To fetch the next page, set `page_token` to the value of the `next_page_token` response.
sort_field optional string	The field to sort on. Can be `full_name`, `email`, `delivery`, `joined`.
sort_dir optional string	Sort direction. Can be 'asc' or 'desc'.

Definition

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

Example Request

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

Example Successful Response

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

Get Subscription

Get a subscription to a single group.

Query Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.

Definition

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

Example Request

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

Example Successful Response

{
  "id": 1,
  "user_id": 12, 
  "group_id": 2,
  "group_name": "groupname",
  "mod_status": "sub_modstatus_none",
  "post_status": "sub_poststatus_normal",
  "email_delivery": "email_delivery_single",
  "pending_messages": 0,
  "pending_subs": 0,
}

Update Subscription

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

POST Parameters

sub_id required number	Subscription ID
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 the subscription object if the update succeeded. Returns an error if update parameters are invalid (e.g. specifying an invalid parameter). Below are the unique errors to this call.

Additional Errors

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.

Definition

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

Example Request

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

Example Successful Response

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

Example Error Response

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

Delete Subscription

Delete a subscription.

POST Parameters

sub_id required	ID of the subscription to delete

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.

Definition

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

Example Request

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

Example Error Response

    {
      "object": "error",
      "type": "bad_request",
      "extra": "you are the only owner"
    }

Join Group - NOT YET IMPLEMENTED

Join a group

Query Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.

Successful Response Attributes

TBD

Definition

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

Example Request

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

Successful Response

HTTP 200

Example Error Response

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

Actions involving a specific group.

Get Permissions

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

Permissions Needed

None.

Query Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.

Definition

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

Example Request

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

Example Successful Response

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

Example Error Response

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

Create A 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`
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 nae.
"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.

Definition

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

Example Request

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

Successful Response

HTTP 200

Example Error Response

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

Create A Sub Group

Create a subgroup.

Permissions Needed

You must have the manage_subgroups permission to use this call.

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name 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`
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.

Definition

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

Example Request

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

Successful Response

HTTP 200

Example Error Response

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

Get Group Settings

Get the group settings

Permissions Needed

You must have the manage_group_settings permission to use this call.

Query Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.

Definition

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

Example Request

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

Example Successful Response

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

Get Subgroups

Get a group's subgroups.

Permissions Needed

You must have the manage_group_settings permission to use this call.

Query Parameters

group_id number	ID of the parent group. Either `group_id` or `group_name` must be specified.
group_name 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 'desc'.

Definition

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

Example Request

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

Example Successful Response

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

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

Definition

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

Example Request

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

Example Error Response

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

Delete Group

Delete a group or a subgroup.

Permissions Needed

You must have the delete_group permission to use this call.

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.
understand required string	The string "I understand".
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.

Definition

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

Example Request

$ curl "https://api.groups.io/v1/deletegroup" \
-u AUTHENTICATION_TOKEN: \
-d group_id=2 \
-d understand=I+understand

Successful Response

HTTP 200

Example Error Response

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

Actions involving the members of a group.

Get Members

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

Permissions Needed

You must have the view_members permission to use this call.

Query Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name 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'.

Notes

If you do not have the manage_pending_members permission, you cannot specify the type pending.
If you do not have the ban_members permission, you cannot specify the type banned.

Definition

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

Example Request

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

Example Successful Response

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

Get Member

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

Permissions Needed

You must have the view_members permission to use this call.

Query Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.
sub_id required number	ID of the member subscription

Definition

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

Example Request

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

Example Successful Response

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

Search Members

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

Permissions Needed

You must have the view_members permission to use this call.

Query Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name 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'.

Definition

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

Example Request

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

Example Successful Response

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

Update Member

Change a member's subscription.

Permissions Needed

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

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.
sub_id required number	ID of the subscription.
email optional string	If the group is not a basic group, you can change the member's email address. This will change all subscriptions associated with this account to the new email address.
post_status optional string	Posting status, can be `sub_poststatus_normal`, `sub_poststatus_allowed`, `sub_poststatus_moderated`, `sub_poststatus_notallowed`, `sub_poststatus_newusermoderated`, `sub_poststatus_modfirstmessage`, `sub_poststatus_modstartedtopics`
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
signature optional string	Signature to sign messages
use_signature optional boolean	If true, sign messages from the web with the signature
use_signature_email optional boolean	If true, sign messages received in email with the signature
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`, `sub_perm_viewmembers`
pending_msg_notify optional string	Notify about pending messages, can be `sub_notify_email`, `sub_notify_none`
pending_sub_notify optional string	Notify about pending subscriptions, can be `sub_notify_email`, `sub_notify_none`
sub_notify optional string	Notify when someone joins the group, can be `sub_notify_email`, `sub_notify_none`
storage_notify optional string	Notify when storage limits are reached, can be `sub_notify_email`, `sub_notify_none`
sub_group_notify optional string	Notify when a subgroup is created, can be `sub_notify_email`, `sub_notify_none`
message_report_notify optional string	Notify when someone reports a message, can be `sub_notify_email`, `sub_notify_none`
owner_msg_notify optional string	Receive messages sent to the +owner address, can be `sub_ownermsg_notify_all`, `sub_ownermsg_notify_subs`, `sub_ownermsg_notify_none`

Returns

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

Additional Errors

"bad_request"	"sole group owner" 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.

Definition

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

Example Request

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

Example Error Response

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

Send a Bounce Probe

Send a bounce probe.

Permissions Needed

You must have the manage_member_subscription_options permission to use this call.

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.
sub_id required number	ID of the subscription.

Returns

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

Additional Errors

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

Definition

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

Example Request

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

Example Error Response

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

Send a Confirmation Email

Send a confirmation email.

Permissions Needed

You must have the manage_member_subscription_options permission to use this call.

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.
sub_id required number	ID of the subscription.

Returns

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

Additional Errors

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

Definition

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

Example Request

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

Example Error Response

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

Ban Member

Ban this member.

Permissions Needed

You must have the ban_members permission to use this call.

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.
sub_id required number	ID of the subscription.

Returns

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

Additional Errors

bad_request	"user already banned" is returned if the member's `status` is already `sub_status_banned`
bad_request	"member cannot be a moderator or owner" is returned if the member's `mod_status` is not `sub_modstatus_none`

Definition

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

Example Request

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

Example Error Response

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

Approve Pending Member

Approve a pending member.

Permissions Needed

You must have the manage_pending_members permission to use this call.

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.
sub_id required number	ID of the subscription.

Returns

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

Additional Errors

Notes

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

Definition

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

Example Request

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

Example Error Response

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

Remove Member

Remove a member from a group.

Permissions Needed

You must have the remove_members permission to use this call.

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name string	Name of the group. Either `group_id` or `group_name` must be specified.
sub_id required number	ID of the subscription.

Returns

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

Additional Errors

Notes

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

Definition

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

Example Request

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

Example Error Response

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

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 number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name 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.

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

bad_request	"sole group owner" is returned if the member is the only owner of the group.

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.

Definition

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

Example Request

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

Example Error Response

    {
      "object": "bulk_remove_results",
      "errors": [
        {
          "object": "remove_error",
          "email": "test@example.com",
          "status": "bulk_remove_not_a_member"
        },
        {
          "object": "remove_error",
          "email": "john@smith.com",
          "status": "bulk_remove_sole_group_owner"
        }
      ],
      "total_emails": 3,
      "removed": 1
    }

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 number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name 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.
subject optional string
message optional string
subgroupids optional string	A comma separated list of IDs of sub groups to also add these people to.

Returns

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

Additional Errors

bad_request	"basic group" is returned if the group is not a premium or enterprise group.
bad_request	"direct add in subgroup" is returned if the group_id refers to a subgroup and not a main group.
bad_request	"group is not a subgroup" is returned if a group ID in `subgroupids` refers to a group that is not a subgroup of the group.
pending_adds	Is returned if the adds require approval. The adds will take place once they have been reviewed.

Notes

For premiun 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 message is specified and there is an active Direct Add member notice, it will be updated with the message.
If a message is specified and there is no active Direct Add member notice, one will be created.

Definition

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

Example Request

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

Example Successful Response

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

Invite

Invite people to join a group.

Permissions Needed

You must have the invite_members permission to use this call.

POST Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name 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.
subject optional string
message optional string

Returns

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

Additional Errors

bad_request	"invite in subgroup" is returned if the group_id refers to a subgroup and not a main group.
pending_invites	Is returned if the invites require approval. The invites will take place once they have been reviewed.

Notes

For basic and premium groups, there is a limit to the number of invites that can be sent from a group per-day. Go over that limit and the pending_invites message will be returned. There is no limit for Enterprise groups.
If a message is specified and there is an active Invite member notice, it will be updated with the message.
If a message is specified and there is no active Invite member notice, one will be created.

Definition

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

Example Request

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

Example Successful Response

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

Actions involving message 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 optional 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 optional 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'.

Successful Response Attributes

id
number

ID of the topic

group_id
number

ID of the group

subject
string

Subject of the topic

summary
string

Summary of the first message in the topic

poster
object

Poster of the first message in the topic

Attributes for poster object

name string	Name of the poster to be displayed
user_id number	ID of the poster (may be 0)
user_name string	User name of the post (may be empty)

num_messages
number

The number of messages in the topic

is_sticky
boolean

If the topic is sticky

is_moderated
boolean

If the topic is moderated

is_closed
boolean

If the topic is closed

reply_to
string, one of

most_recent_message
date

Date of the most recent message

hashtags
array

Array of hashtag objects

Attributes for hashtags object

id number	ID of the hashtag
name string	Name of the hashtag
color string	Hex color of the hashtag
group_id number	ID of the group
mods_only_post boolean
mods_only_replies boolean
no_email boolean
moderated boolean
special boolean
replies_unmoderated boolean
locked boolean
until string, one of
close_instead_of_delete boolean
description string
color_name string
color_hex string
reply_to string, one of
topic_count number
last_message_date date

Definition

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

Example Request

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

Example Successful Response

{
  "object": "list",
  "total_count": 133,
  "start_item": 1,
  "end_item": 1,
  "has_more": true,
  "next_page_token": 2,
  "data": [
    {
      "id": 1,
      "object": "topic",
      "created": "2014-09-29T23:39:41-07:00",
      "updated": "2018-10-30T12:12:02.050310598-07:00",
      "group_id": 1,
      "group_subject_tag": "[beta]",
      "subject": "Announcement in other moderator groups?",
      "summary": "Lorem ipsum consectetur sunt ea ad in dolore dolore deserunt magna ut labore anim proident.",
      "poster": {
        "name": "Poster name",
        "user_name": "",
        "user_id": 0
      },
      "num_messages": 4,
      "is_sticky": false,
      "is_moderated": false,
      "is_closed": false,
      "reply_to": "thread_reply_group_default",
      "most_recent_message": "2014-09-30T08:15:54-07:00",
      "hashtags": [
        {
          "id": 11,
          "object": "hashtag",
          "created": "2018-10-30T12:13:35.055905988-07:00",
          "group_id": 1,
          "name": "polls",
          "mods_only_post": false,
          "mods_only_replies": false,
          "no_email": false,
          "moderated": false,
          "special": false,
          "replies_unmoderated": false,
          "locked": false,
          "until": "hash_tag_delete_forever",
          "close_instead_of_delete": false,
          "description": "",
          "color_name": "tag_cerulean_blue",
          "color_hex": "#4191d6",
          "reply_to": "thread_reply_group_default",
          "topic_count": 1,
          "last_message_date": "2018-10-30T12:13:35.054086063-07:00"
        },
        {
          "id": 9,
          "object": "hashtag",
          "created": "2018-10-30T12:13:33.697439788-07:00",
          "group_id": 1,
          "name": "wishlist",
          "mods_only_post": false,
          "mods_only_replies": false,
          "no_email": false,
          "moderated": false,
          "special": false,
          "replies_unmoderated": false,
          "locked": false,
          "until": "hash_tag_delete_forever",
          "close_instead_of_delete": false,
          "description": "",
          "color_name": "tag_cerulean_blue",
          "color_hex": "#4191d6",
          "reply_to": "thread_reply_group_default",
          "topic_count": 4,
          "last_message_date": "2018-10-30T12:13:35.069679546-07:00"
        }
      ]
    }
  ]
}

Download Archives - DISABLED

Download the archives of a group. This is currently disabled due to abuse.

Permissions Needed

You must have the view_archives permission to use this call.

Query Parameters

group_id number	ID of the group. Either `group_id` or `group_name` must be specified.
group_name 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.

Definition

https://api.groups.io/v1/downloadarchives?group_id=2

Example Request

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

Successful Response

HTTP 200 and a compressed ZIP file containing the archives in mbox format.

Example Error Response

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

API Reference - ALPHA

API Endpoint

Versioning And Change Log

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

Errors

Example Error Response

Pagination

Example Response

Libraries

Authentication

Login

Definition

Example Request

Example Successful Response

Objects

The Bulk Remove Results Object

Example Response

The Direct Add Results Object

Attributes for errors object

Example Response

The Group Object

Example Response

The Hashtag Object

Example Response

The Invite Results Object

Attributes for errors object

Example Response

The Permissions Object

Example Response

The Subscription Object

Example Response

The Subscription Plus Object

Example Response

The Topic Object

Attributes for poster object

Example Response

The User Object

Example Response

User

Get User

Definition

Example Request

Example Successful Response

Update User

Definition

Example Request

Example Successful Response

Example Error Response

Get Subscriptions

Definition

Example Request

Example Successful Response

Get Subscription

Definition

Example Request

Example Successful Response

Update Subscription

Definition

Example Request

Example Successful Response

Example Error Response

Delete Subscription

Definition

Example Request

Example Error Response

Join Group - NOT YET IMPLEMENTED

Definition

Example Request

Successful Response

Example Error Response

Group

Get Permissions

Definition

Example Request

Example Successful Response

Example Error Response

Create A Group

Definition

Example Request

Successful Response