# Sub Organizations ## Create a sub-organization. **post** `/print-mail/v1/sub_organizations` When creating a user through the API, the verifiedEmail field will automatically be set to true. However, if public signups are used, the email will need to be verified by the user. ### Body Parameters - `countryCode: string` The country code of the sub-organization. - `email: string` The email of the user to be created alongside the sub-organization. - `name: string` The name of the user to be created alongside the sub-organization. - `organizationName: string` The name of the sub-organization. - `password: string` The password of the user to be created alongside the sub-organization. - `phoneNumber: optional string` The phone number of the user to be created alongside the sub-organization. ### Returns - `subOrganization: SubOrganization` The Sub-Organization object. - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. - `user: object { id, apiKeys, email, 9 more }` The user object. - `id: string` A unique ID prefixed with `user_`. - `apiKeys: array of object { value, activeUntil }` The user's API keys. Contains live and test mode API keys. - `value: string` The value of the API key. - `activeUntil: optional string` An optional date which the API key is active until. After this date, the API key will no longer be valid. - `email: string` The email of the user. - `name: string` The name of the user. - `organization: string` A unique ID prefixed with `user_`. - `pendingInvite: boolean` Indicates if the user has a pending invite. - `roles: array of string` The roles given to the user. Roles can be used to restrict access for users. - `verifiedEmail: boolean` Indicates if the user has a verified email or not. - `emailPreferences: optional EmailPreferences` A set of preferences for how a user should receive emails. - `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` - `lastLoginTime: optional string` The date and time at which the user last logged in. - `phoneNumber: optional string` The phone number of the user. - `previousEmails: optional array of string` A list of emails the user has previously had. If a user has changed their email before, this list will be populated with all of the emails they once had. ### Example ```http curl https://api.postgrid.com/print-mail/v1/sub_organizations \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "countryCode": "CA", "email": "suborg@postgrid.com", "name": "Calvin", "organizationName": "PostGrid", "password": "very-strong-password" }' ``` #### Response ```json { "user": { "id": "user_abc123def456ghi6789", "pendingInvite": false, "organization": "org_abc123def456ghi6789", "email": "user@postgrid.com", "name": "Calvin", "apiKeys": [ { "value": "live_abcdefg" }, { "value": "test_abcdefg" } ], "verifiedEmail": true, "roles": [ "role_abc123def456ghi6789" ] }, "subOrganization": { "usage": 0, "limit": 500, "spend": 0, "name": "PostGrid", "countryCode": "CA", "id": "sub_org_abc123def456ghi6789", "object": "sub_org", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } } ``` ## List sub-organizations. **get** `/print-mail/v1/sub_organizations` List sub-organizations. ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `data: array of SubOrganization` - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/sub_organizations \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "usage": 0, "limit": 500, "spend": 0, "name": "PostGrid", "countryCode": "CA", "id": "sub_org_abc123def456ghi6789", "object": "sub_org", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ] } ``` ## Get a sub-organization. **get** `/print-mail/v1/sub_organizations/{id}` Get a sub-organization. ### Path Parameters - `id: string` ### Returns - `SubOrganization object { id, countryCode, createdAt, 6 more }` The Sub-Organization object. - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. ### Example ```http curl https://api.postgrid.com/print-mail/v1/sub_organizations/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "usage": 0, "limit": 500, "spend": 0, "name": "PostGrid", "countryCode": "CA", "id": "sub_org_abc123def456ghi6789", "object": "sub_org", "createdAt": "2020-11-12T23:23:47.974Z", "updatedAt": "2020-11-12T23:23:47.974Z" } ``` ## List users for a sub-organization. **get** `/print-mail/v1/sub_organizations/{id}/users` List users for a sub-organization. ### Path Parameters - `id: string` ### Query Parameters - `limit: optional number` - `search: optional string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip: optional number` ### Returns - `id: string` A unique ID prefixed with `user_`. - `email: string` The email of the user. - `name: string` The name of the user. - `organization: string` A unique ID prefixed with `user_`. - `pendingInvite: boolean` Indicates if the user has a pending invite. - `roles: array of string` The roles given to the user. Roles can be used to restrict access for users. - `verifiedEmail: boolean` Indicates if the user has a verified email or not. - `emailPreferences: optional EmailPreferences` A set of preferences for how a user should receive emails. - `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` - `lastLoginTime: optional string` The date and time at which the user last logged in. - `phoneNumber: optional string` The phone number of the user. - `previousEmails: optional array of string` A list of emails the user has previously had. If a user has changed their email before, this list will be populated with all of the emails they once had. ### Example ```http curl https://api.postgrid.com/print-mail/v1/sub_organizations/$ID/users \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json [ { "id": "user_abc123def456ghi6789", "pendingInvite": false, "organization": "org_abc123def456ghi6789", "email": "user@postgrid.com", "name": "Calvin", "verifiedEmail": true, "roles": [ "role_abc123def456ghi6789" ] } ] ``` ## Domain Types ### Email Preferences - `EmailPreferences object { orderPreviewSendPreference }` A set of preferences for how a user should receive emails. - `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` ### Sub Organization - `SubOrganization object { id, countryCode, createdAt, 6 more }` The Sub-Organization object. - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. ### Sub Organization Create Response - `SubOrganizationCreateResponse object { subOrganization, user }` - `subOrganization: SubOrganization` The Sub-Organization object. - `id: string` A unique ID prefixed with `sub_org_`. - `countryCode: string` The country code of the sub-organization. - `createdAt: string` The UTC time at which this resource was created. - `limit: number` The limit of mailings the sub-organization can send before being charged overages for the month. - `name: string` The name of the sub-organization. - `object: "sub_org"` Always `sub_org`. - `"sub_org"` - `spend: number` The current rolling charge for the sub-organization for the month, in cents. - `updatedAt: string` The UTC time at which this resource was last update. - `usage: number` The amount of mail the sub-organization has sent out this month. - `user: object { id, apiKeys, email, 9 more }` The user object. - `id: string` A unique ID prefixed with `user_`. - `apiKeys: array of object { value, activeUntil }` The user's API keys. Contains live and test mode API keys. - `value: string` The value of the API key. - `activeUntil: optional string` An optional date which the API key is active until. After this date, the API key will no longer be valid. - `email: string` The email of the user. - `name: string` The name of the user. - `organization: string` A unique ID prefixed with `user_`. - `pendingInvite: boolean` Indicates if the user has a pending invite. - `roles: array of string` The roles given to the user. Roles can be used to restrict access for users. - `verifiedEmail: boolean` Indicates if the user has a verified email or not. - `emailPreferences: optional EmailPreferences` A set of preferences for how a user should receive emails. - `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` - `lastLoginTime: optional string` The date and time at which the user last logged in. - `phoneNumber: optional string` The phone number of the user. - `previousEmails: optional array of string` A list of emails the user has previously had. If a user has changed their email before, this list will be populated with all of the emails they once had. ### Sub Organization Retrieve Users Response - `SubOrganizationRetrieveUsersResponse = array of object { id, email, name, 8 more }` - `id: string` A unique ID prefixed with `user_`. - `email: string` The email of the user. - `name: string` The name of the user. - `organization: string` A unique ID prefixed with `user_`. - `pendingInvite: boolean` Indicates if the user has a pending invite. - `roles: array of string` The roles given to the user. Roles can be used to restrict access for users. - `verifiedEmail: boolean` Indicates if the user has a verified email or not. - `emailPreferences: optional EmailPreferences` A set of preferences for how a user should receive emails. - `orderPreviewSendPreference: optional "do_not_send" or "send_live_only" or "send_live_and_test"` The list of preferences for receiving order preview emails. - `"do_not_send"` - `"send_live_only"` - `"send_live_and_test"` - `lastLoginTime: optional string` The date and time at which the user last logged in. - `phoneNumber: optional string` The phone number of the user. - `previousEmails: optional array of string` A list of emails the user has previously had. If a user has changed their email before, this list will be populated with all of the emails they once had.