Groups.io API Reference

API Reference - ALPHA

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

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

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

API Endpoint

api.groups.io

Versioning 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 integer	A limit on the number of objects to be returned, between 1 and 100. Default: `10` Minimum: 1 Maximum: 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

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.

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

Objects

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

The Bulk Remove Results Object#

Response Attributes

object

string read-onlyvalue 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

Attributes for errors

object string read-onlyvalue 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-onlyvalue 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 string read-onlyvalue 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-onlyvalue is "user"	String representing the object’s type. Objects of the same type share the same value.
created string read-only date-time	Created date
updated string read-only date-time	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`
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
restrict_create_hash_tags boolean
bounce_attachments boolean
allow_photos_in_files boolean
email_delivery_default string	Email delivery, can be `email_delivery_single`, `email_delivery_digest`, `email_delivery_special`, `email_delivery_none`, `email_delivery_html_digest`, `email_delivery_summary`
message_selection_default string	Message selection, can be `message_selection_all`, `message_selection_follow_only`, `message_selection_follow_and_first_message`
auto_follow_replies_default boolean
max_attachment_size_default string	Maximum attachment size, can be `max_attachment_size_unlimited`, `max_attachment_size_small`, `max_attachment_size_medium`, `max_attachment_size_large`, `max_attachment_size_none`
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
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.

Example Response

{
  "id": 5,
  "object": "group",
  "created": "2017-08-03T10:18:15.218974479-07:00",
  "updated": "2017-08-15T12:48:41.965409169-07:00",
  "title": "",
  "parent_group_id": 0,
  "name": "test",
  "alias": "main",
  "desc": "This is a description of a test group.",
  "subject_tag": "[test]",
  "footer": "This is my\r\nFooter!!!!",
  "website": "",
  "announce": false,
  "moderated": false,
  "new_users_moderated": true,
  "unmoderate_users_after": 1,
  "restricted": false,
  "allow_non_subs_to_post": false,
  "force_html_emails": false,
  "normalize_html_emails": false,
  "reply_to": "group_reply_to_group",
  "remove_other_reply_options": false,
  "privacy": "group_privacy_none",
  "members_visible": "group_view_members_subs",
  "subgroup_access": "sub_group_subs",
  "calendar_access": "group_access_limited",
  "files_access": "group_access_limited",
  "database_access": "group_access_limited",
  "wiki_access": "group_access_limited",
  "photos_access": "group_access_limited",
  "member_directory_access": "group_access_limited",
  "polls_access": "polls_access_subscribers",
  "chat_access": "group_access_limited",
  "handle_attachments": "group_attachments_normal",
  "plain_text_only": false,
  "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,
  "restrict_create_hash_tags": false,
  "bounce_attachments": false,
  "allow_photos_in_files": false,
  "email_delivery_default": "email_delivery_none",
  "message_selection_default": "message_selection_all",
  "auto_follow_replies_default": true,
  "max_attachment_size_default": "max_attachment_size_unlimited",
  "default_timezone": "america/los_angeles",
  "allow_downloads": "allow_downloads_no",
  "seperate_footers": false,

  "disable_edits": false,
  "disable_no_email": false,
  "auto_close_threads": false,
  "close_threads_after": 0,
  "auto_moderate_threads": false,
  "moderate_threads_after": 0,
  "subs_count": 10,
  "pending_subs_count": 0,
  "pending_msgs_count": 0,
  "open_chats_count": 0,
  "threads_count": 30,
  "messages_count": 82
}

The Invite Results Object#

Response Attributes

object

string read-onlyvalue 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 string read-onlyvalue 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-onlyvalue 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 integer read-only	Subscription ID
object string read-onlyvalue is "subscription"	String representing the object’s type. Objects of the same type share the same value.
created string read-only date-time	Created date
updated string read-only date-time	Last updated date
user_id integer read-only	User ID
group_id integer read-only	Group ID
status string	Subscription status, can be `sub_status_normal`, `sub_status_pending`, `sub_status_banned`
post_status string	Posting status, can be `sub_poststatus_normal`, `sub_poststatus_allowed`, `sub_poststatus_moderated`, `sub_poststatus_notallowed`, `sub_poststatus_newusermoderated`
email_delivery string	Email delivery, can be `email_delivery_single`, `email_delivery_digest`, `email_delivery_special`, `email_delivery_none`, `email_delivery_html_digest`, `email_delivery_summary`
message_selection string	Message selection, can be `message_selection_all`, `message_selection_follow_only`, `message_selection_follow_and_first_message`
auto_follow_replies boolean
max_attachment_size string	Maximum attachment size, can be `max_attachment_size_unlimited`, `max_attachment_size_small`, `max_attachment_size_medium`, `max_attachment_size_large`, `max_attachment_size_none`
approved_posts number read-only
email string read-only
user_status string read-only	User status, can be `user_status_not_confirmed`, `user_status_confirmed`, `user_status_inactive`, `user_status_bouncing`, `user_status_bounced`
user_name string read-only
timezone string read-only
full_name string
about_me string
about_format string
location string
website string
profile_privacy string	Profile visibility, `profile_private`, `profile_members`, `profile_public`
dont_munge_message_id boolean read-only	Whether to change the message-id of any posted messages
moderator_notes string	Free-form data. This will be empty if the object is 'subscription_plus'.
moderator_notes_updated string read-only date-time
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 string read-only date-time	Date of the most recent message.

Example Response

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

The User Object#

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

Attributes

id integer read-only	ID of the user
object string read-onlyvalue is "user"	String representing the object’s type. Objects of the same type share the same value.
created string read-only date-time	Date the user was created
updated string read-only date-time	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 integer	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"
}

User

Actions involving the authenticated user.

Get User#

Return the user information associated with an authentication token.

Definition

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

Example Request

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

Example Successful Response

{
  "id": 3,
  "created": "2017-08-03T10:18:15.218974479-07:00",
  "updated": "2017-08-03T10:21:22.482757663-07:00",
  "email": "john@smith",
  "full_name": "John Smith",
  "user_name": "",
  "timezone": "Pacific/Midway",
  "status": "user_status_confirmed",
  "profile_photo_id": "",
  "has_profile_photo": false,
  "post_pref": "user_postpref_markdown",
  "per_page_pref": "user_per_page_pref20",
  "allow_facebook_login": false,
  "allow_google_login": false,
  "two_factor_enabled": false,
  "recovery_codes": "",
  "dont_munge_message_id": false,
  "about_me": "",
  "about_format": "about_html",
  "location": "",
  "website": "",
  "time_pref": "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 integer	A limit on the number of objects to be returned, between 1 and 100. Default: `10` Minimum: 1 Maximum: 100
page_token optional opaque	A cursor for use in pagination. To fetch the next page, set `page_token` to the value of the `next_page_token` response.
sort_field optional string	The field to sort on. Can be `full_name`, `email`, `delivery`, `joined`.
sort_dir optional string	Sort direction. Can be 'asc' or 'desc'.

Definition

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

Example Request

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

Example Successful Response

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

Get Subscription#

Get a subscription to a single group.

Query Parameters

group_id integer	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,
  "name": "Group1",
  "group_id": 2,
  "mod_status": "sub_modstatus_none",
  "post_status": "sub_poststatus_normal",
  "email_delivery": "email_delivery_single",
  "pending_messages": 0,
  "pending_subs": 0,
}

Update Subscription#

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

POST Parameters

sub_id required integer	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,
    "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 - NI#

Join a group

Query Parameters

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

Group

Actions involving a specific group.

Get Permissions#

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

Permissions Needed

None.

Query Parameters

group_id integer	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 integer	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 integer	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",
  "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,
  "restrict_create_hash_tags": false,
  "bounce_attachments": false,
  "allow_photos_in_files": false,
  "email_delivery_default": "email_delivery_none",
  "message_selection_default": "message_selection_all",
  "auto_follow_replies_default": true,
  "max_attachment_size_default": "max_attachment_size_unlimited",
  "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,
  "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 integer	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 integer	A limit on the number of objects to be returned, between 1 and 100. Default: `10` Minimum: 1 Maximum: 100
page_token optional opaque	A cursor for use in pagination. To fetch the next page, set `page_token` to the value of the `next_page_token` response.
sort_field optional string	The field to sort on. Can be `created`, `name`.
sort_dir optional string	Sort direction. Can be 'asc' or 'desc'.

Definition

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

Example Request

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

Example Successful Response

{
  "object": "list",
  "total_count": 1,
  "start_item": 1,
  "end_item": 1,
  "has_more": false,
  "next_page_token": 0,
  "data": [
    {
      "id": 8,
      "object": "group",
      "created": "2017-08-07T21:33:32.851703356-07:00",
      "updated": "2017-08-15T12:48:41.986378376-07:00",
      "title": "",
      "parent_group_id": 5,
      "name": "beta+first",
      "alias": "",
      "desc": "",
      "subject_tag": "[first]",
      "footer": "",
      "website": "",
      "announce": false,
      "moderated": false,
      "new_users_moderated": false,
      "unmoderate_users_after": 0,
      "restricted": false,
      "allow_non_subs_to_post": false,
      "force_html_emails": false,
      "normalize_html_emails": false,
      "reply_to": "group_reply_to_group",
      "remove_other_reply_options": false,
      "privacy": "sub_group_privacy_unlisted",
      "members_visible": "group_view_members_moderators",
      "subgroup_access": "sub_group_subs",
      "calendar_access": "group_access_limited",
      "files_access": "group_access_limited",
      "database_access": "group_access_limited",
      "wiki_access": "group_access_limited",
      "photos_access": "group_access_limited",
      "member_directory_access": "group_access_limited",
      "polls_access": "polls_access_subscribers",
      "chat_access": "group_access_limited",
      "handle_attachments": "group_attachments_normal",
      "plain_text_only": false,
      "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,
      "restrict_create_hash_tags": false,
      "bounce_attachments": false,
      "allow_photos_in_files": false,
      "email_delivery_default": "email_delivery_single",
      "message_selection_default": "message_selection_all",
      "auto_follow_replies_default": false,
      "max_attachment_size_default": "max_attachment_size_unlimited",
      "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,
      "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 integer	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`
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
restrict_create_hash_tags optional boolean
bounce_attachments optional boolean
allow_photos_in_files optional boolean
email_delivery_default optional string	Email delivery default, can be `email_delivery_single`, `email_delivery_digest`, `email_delivery_special`, `email_delivery_none`, `email_delivery_html_digest`, `email_delivery_summary`
message_selection_default optional string	Message selection, can be `message_selection_all`, `message_selection_follow_only`, `message_selection_follow_and_first_message`
auto_follow_replies_default optional boolean
max_attachment_size_default optional string	Maximum attachment size, can be `max_attachment_size_unlimited`, `max_attachment_size_small`, `max_attachment_size_medium`, `max_attachment_size_large`, `max_attachment_size_none`
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
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 integer	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": ""
    }

Members

Actions involving the members of a group.

Get Members#

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

Permissions Needed

You must have the view_members permission to use this call.

Query Parameters

group_id integer	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	The type of member to be returned, can be `pending`, `banned`, `mods`, `members`. See Notes for restrictions. Default: `members`
limit optional integer	A limit on the number of objects to be returned, between 1 and 100. Default: `10` Minimum: 1 Maximum: 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 integer	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 integer	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 integer	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 integer	A limit on the number of objects to be returned, between 1 and 100. Default: `10` Minimum: 1 Maximum: 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 integer	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 integer	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`
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 integer	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 integer	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 integer	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 integer	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 integer	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 integer	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 integer	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 integer	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 integer	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 integer	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 integer	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 integer	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 integer	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" 
  ]
}

API Reference - ALPHA

API Endpoint

Versioning And Change Log#

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

Errors#

Pagination#

Libraries#

Authentication

Login#

Objects

The Bulk Remove Results Object#

The Direct Add Results Object#

The Group Object#

The Invite Results Object#

The Permissions Object#

The Subscription Object#

The Subscription Plus Object#

The User Object#

User

Get User#

Update User#

Get Subscriptions#

Get Subscription#

Update Subscription#

Delete Subscription#

Join Group - NI#

Group

Get Permissions#

Create A Group#

Create A Sub Group#

Get Group Settings#

Get Subgroups#

Update Group#

Delete Group#

Members

Get Members#

Get Member#

Search Members#

Update Member#

Send a Bounce Probe#

Send a Confirmation Email#

Ban Member#

Approve Pending Member#

Remove Member#

Bulk Remove Members#

Direct Add#

Invite#

Archives

Get Topics - NI#

Download Archives#