TeamBeam API Version 2
API Endpoint
https://free.teambeam.de/api/skp/v2This document describes version 2 of the TeamBeam Transfer API.
This version is currently being developed. Eventually, it will replace version 1 of the API.
Getting Started ¶
Transport ¶
The TeamBeam API is available via HTTPS only. The hostname matters, most entities are bound to a specific hostname, and accessing them on other hostnames will often not work.
SSL 2.0 and SSL 3.0 are disabled.
The base URI for all resources is:
https://{hostname}/api/skp/v2
Authentication ¶
Most requests require authentication in the form of bearer tokens. See authentication.
Some unauthenticated requests may use a cookie-based session.
Rate Limiting ¶
Many resources are protected against misuse or overload caused by badly behaving clients through rate limits according to the Leaky Bucket Algorithm as a Queue concept. Buckets are initially empty. Every request attempts to add a drop to the bucket. If the capacity does not allow this, the request is rejected (see ‘HTTP 509 Rate Limit Exceeded’ in section ‘Error handling’). Buckets drain over time, reducing their specific level and allowing new requests.
HTTP headers inform about the current bucket properties:
-
X-RateLimit-Limit
The total capacity of the current bucket.
Example:
X-RateLimit-Limit: 60 -
X-RateLimit-Remaining
The remaining capacity in the current bucket. Once this value is exhausted, future requests will be rejected until the bucket has been drained sufficiently.
Example:
X-RateLimit-Remaining: 42
Different resources use different buckets:
| Resource | Bucket Identifier | Capacity | Drainrate [1/s] |
|---|---|---|---|
| Login | Email-address of user | 3 | 1/15 |
| Get Onetime Key | User-ID | 10 | 1/30 |
| Environment | no limit | n/a | n/a |
| Other resources | session ID | 60 | 1 |
API Deprecation ¶
Over time, the backend may change and a new version of the API will be released. To inform developers and clients of upcoming changes, the server indicates API deprecation by sending a Warning header with warning-code 229.
Example:
Warning: 299 - “API Deprecation Warning: Support for this request will be dropped soon, please update your client.”
While API deprecation is indicated, the API call will still function as documented. At a later stage, support for individual API calls up to the complete API-path may be dropped. This is indicated by responding with HTTP status code 410 (see section ‘Error handling’).
Payload format ¶
Unless explicitely stated, request and response bodies are encoded in JSON format. Appropriate headers (Content-Type: application/json, Accept: application/json) must be set.
Timestamps are encoded in ISO 8601 format, including timezone offset from UTC. Example:
{ “validDate”: “2037-12-31T15:29:59+00:00” }
Error handling ¶
The API responds with different HTTP Status Codes and messages:
-
HTTP 400 Bad Request
The request cannot be processed for syntax reasons. This could be because of a missing field, an incorrect type or an invalid value. The error message might provide more information. Check your code against the documentation. Retrying the request will not improve your chances of success.
Example:
{ "error": { "code": 400001, "message": "The request cannot be fulfilled.", "details": ["Invalid or unsupported value.", "Please consult the documentation."] } } -
HTTP 401 Not Authorized
Your request is missing an authenticated session ID, your session ID has expired, or your user is not valid. Obtain a new session and/or authenticate it (see the AuthResource).
-
HTTP 403 Forbidden
Your request was syntactically correct, but violated somehing else. Possible reasons are feature- and/or contract-limitations, accessing someone else’s data without authorization. Retrying the request will lead to the same result. The details of the message will provide more details.
Example:
{ "error": { "code": 403001, "message": "This request is forbidden.", "details": ["TTL is not acceptable"] } } -
HTTP 404 Not Found
The request could not be fulfilled, since the resource or entity at the URI does not exist (anymore). Retrying is futile.
-
HTTP 405 Method Not Allowed
The resource or entity does not support the HTTP method. Please consult the documentation.
-
HTTP 406 Not Acceptable
The backend cannot supply the response in the requested mediatype (as per the
Acceptrequest header). Please consult the documentation. You can retry your request, specifying appropriate headers. -
HTTP 409 Conflict
The request was not successful, because the a persistence-opertion failed. This can be temporary, or because another operation has modified the data in the meantime. Reread your data again, apply your changes and retry the request. You haven’t broken anything yet.
-
HTTP 410 Gone
The request was once valid but is no longer acceptable. This is a permanent situation. It indicates that parts of the API have since been deprecated and support for them has been dropped. It is recommended to consult the documentation and update clients.
-
HTTP 413 Request Entity Too Large
The backend is unwilling or unable to process a request body of this size.
-
HTTP 415 Unsupported Mediatype
The backend does not support the request payload, as announced in the
Content-Typeheader. -
HTTP 416 Range Not Satisfiable
This occurs when an upload or download request does not provide acceptable values for headers
RangeorContent-Range. -
HTTP 429 Rate Limit Exceeded
The request was not accepted because of a rate limit violation. The API is protected against overload and bruteforce attacks with rate limits. See the section on rate limiting for details. The response contains a
Retry-Afterheader (in seconds) to assist in retrying the request again.Example:
Retry-After: 23 -
HTTP 500 Server Error
Oops! It looks like something went horribly wrong in the backend. You might want to get in touch with us.
-
HTTP 503 Maintenance
The host you’re addressing is currently undergoing maintenance and is not serving requests. You can retry your request until is being accepted again.
Public resources ¶
Environment ¶
GET https://free.teambeam.de/api/skp/v2/environment
Responses
Headers
Content-Type: application/jsonBody
{
"serverVersion": "5.1.4",
"availableTtl": [
1,
1
],
"defaultTtl": 3,
"priorityEnabled": true,
"protectionLevel": "none"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"serverVersion": {
"type": "string",
"description": "The version of the backend server"
},
"availableTtl": {
"type": "array",
"description": "Contains all allowed values for expiration time of new transfers, in days."
},
"defaultTtl": {
"type": "number",
"description": "Default expiration time of new transfers, in days."
},
"priorityEnabled": {
"type": "boolean",
"description": "If true, users can choose to set a priority value when sending a new transfer."
},
"protectionLevel": {
"type": "string",
"enum": [
"none",
"password",
"recipientAuthentication"
],
"description": "The required level of protection for new transfers."
}
},
"required": [
"serverVersion",
"availableTtl",
"defaultTtl",
"priorityEnabled",
"protectionLevel"
]
}Fetch environmentGET/environment
Returns configuration values specific to the adminunit and its configuration.
Mailbox ¶
GET https://free.teambeam.de/api/skp/v2/public/mailbox/john.doe
Responses
Headers
Content-Type: application/jsonBody
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"description": "Name of the person"
},
"email": {
"type": "string",
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
]
}Vanitylink is not valid
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Nothing found
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Resolve mailboxGET/public/mailbox/{key}
Resolves a vanity link into the details of a mailbox. Invalid vanity links are rejected.
URI Parameters
- key
string(required) Example: john.doeVanity link or UID of person
HEAD https://free.teambeam.de/api/skp/v2/public/mailbox/john.doe
Responses
Headers
Content-Type: application/jsonHeaders
Content-Type: application/jsonHeaders
Content-Type: application/jsonTest vanity linkHEAD/public/mailbox/{key}
Tests if the given key is valid and matches a mailbox.
URI Parameters
- key
string(required) Example: john.doeVanity link or UID of person
POST https://free.teambeam.de/api/skp/v2/public/mailbox/john.doe
Requests
Headers
Content-Type: application/jsonBody
{
"subject": "Hello, world!",
"description": "Hello, world!",
"deliveryNotification": false,
"ttl": 1,
"priority": 3,
"protection": "none",
"password": "Hello, world!",
"anonSender": "John Doe",
"anonEmail": "john.doe@example.org"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Subject of the new transfer"
},
"description": {
"type": "string",
"description": "Description of the new transfer"
},
"deliveryNotification": {
"type": "boolean",
"description": "If true, the uploader is informed when the new transfer has been accessed"
},
"ttl": {
"type": "number",
"description": "Number of days before the transfer expires. If not yet, the adminunit default is used."
},
"priority": {
"type": "number",
"description": "From highest (1) to lowest (5)"
},
"protection": {
"type": "string",
"enum": [
"none",
"password",
"recipientAuthentication"
],
"description": "Default: `none`"
},
"password": {
"type": "string",
"description": "Required if protection is set to `password`"
},
"anonSender": {
"type": "string",
"description": "Name of the uploader"
},
"anonEmail": {
"type": "string",
"description": "Email address of the uploader"
}
},
"required": [
"anonSender",
"anonEmail"
]
}Responses
The reservation has been created.
Headers
Content-Type: application/json
Authorization: Bearer {... reservation-specific access token ...}Body
{
"subject": "Hello, world!",
"description": "Hello, world!",
"deliveryNotification": false,
"ttl": 1,
"priority": 3,
"protection": "none",
"password": "Hello, world!",
"uid": "s528x16vo52j18la0yvv",
"anonSender": "John Doe",
"anonEmail": "john.doe@example.org",
"recipients": [
{
"uid": "36odq_1mklfavec7",
"name": "Alice",
"email": "alice@example.org",
"destinationType": "to"
}
],
"folder": 1,
"objects": [
{
"clientId": "abc123",
"name": "Sales_Forecast.xlsx",
"size": 200000,
"intendedSize": 410339
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Subject of the new transfer"
},
"description": {
"type": "string",
"description": "Description of the new transfer"
},
"deliveryNotification": {
"type": "boolean",
"description": "If true, the uploader is informed when the new transfer has been accessed"
},
"ttl": {
"type": "number",
"description": "Number of days before the transfer expires. If not yet, the adminunit default is used."
},
"priority": {
"type": "number",
"description": "From highest (1) to lowest (5)"
},
"protection": {
"type": "string",
"enum": [
"none",
"password",
"recipientAuthentication"
],
"description": "Default: `none`"
},
"password": {
"type": "string",
"description": "Required if protection is set to `password`"
},
"uid": {
"type": "string",
"description": "Readonly. UID of the reservation"
},
"anonSender": {
"type": "string",
"description": "Name of the uploader. For mailbox transfers, this field is required."
},
"anonEmail": {
"type": "string",
"description": "Email address of the uploader. For mailbox transfers, this field is required."
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"36odq_1mklfavec7"
],
"description": "UID of the person, if found."
},
"name": {
"type": "string",
"enum": [
"Alice"
],
"description": "Name of the recipient"
},
"email": {
"type": "string",
"enum": [
"alice@example.org"
],
"description": "Email address of recipient"
},
"destinationType": {
"type": "string",
"enum": [
"to",
"cc",
"bcc"
]
}
},
"required": [
"email",
"destinationType"
],
"additionalProperties": false
},
"description": "List of recipients. Can be empty for archive-only- or drop-transfers."
},
"folder": {
"type": "number",
"description": "References a folder of an archive as the destination."
},
"objects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientId": {
"type": "string",
"enum": [
"abc123"
],
"description": "A client-set reservation-unique identifier of an object."
},
"name": {
"type": "string",
"enum": [
"Sales_Forecast.xlsx"
],
"description": "The filename of the object."
},
"size": {
"type": "number",
"enum": [
200000
],
"description": "Actual size of the file in number of Bytes."
},
"intendedSize": {
"type": "number",
"enum": [
410339
],
"description": "Expected file size in Bytes."
}
},
"required": [
"clientId",
"name",
"size",
"intendedSize"
],
"additionalProperties": false
},
"description": "Readonly. List of objects that are attached to the reservation."
}
},
"required": [
"uid",
"recipients",
"objects"
]
}Vanitylink is not valid
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Nothing found
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Create reservationPOST/public/mailbox/{key}
This resource creates the reservation to send a transfer to the referenced mailbox.
No authentication is required, however the sender must provide their own details in fields anonSender and anonEmail.
Once created, the reservation can be updated and files can be attached. When finished, the reservation can be confirmed which closes it and delivers the transfer to the mailbox owner.
The response contains a reservation-specific access token in the response header Authorization. The token is valid for 48h and authenticates changes to the reservation, file uploads as well as reservation-confirmation. After this time, the reservation expires automatically.
URI Parameters
- key
string(required) Example: john.doeVanity link or UID of person
Mailbox group ¶
GET https://free.teambeam.de/api/skp/v2/public/mailboxgroup/sales_east
Responses
Headers
Content-Type: application/jsonBody
{
"name": "Sales Team east",
"description": "Direct mailbox for the sales team",
"vanityLink": "sales_east",
"mailboxes": [
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}
],
"uid": "ffo8csxbftm.enef"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the person"
},
"description": {
"type": "string",
"description": "Optional description of the mailbox"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
},
"mailboxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"s_xm0g7br4lpoq5d"
],
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"enum": [
"John Doe"
],
"description": "Name of the person"
},
"email": {
"type": "string",
"enum": [
"john@example.org"
],
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"enum": [
"john.doe"
],
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
],
"additionalProperties": false
},
"description": "List of mailboxes in the group"
},
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
}
},
"required": [
"name",
"vanityLink",
"mailboxes",
"uid"
]
}Vanitylink is not valid
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Nothing found
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Resolve mailbox groupGET/public/mailboxgroup/{key}
Resolves a vanity link into the details of a mailbox group. Invalid vanity links are rejected.
URI Parameters
- key
string(required) Example: sales_eastVanity link or UID of mailbox group
HEAD https://free.teambeam.de/api/skp/v2/public/mailboxgroup/sales.east
Responses
Headers
Content-Type: application/jsonHeaders
Content-Type: application/jsonHeaders
Content-Type: application/jsonTest vanity linkHEAD/public/mailboxgroup/{key}
Tests if the given key is valid and matches a mailbox-group.
URI Parameters
- key
string(required) Example: sales.eastVanity link or UID of mailbox group
Authentication ¶
In order to access privileged data or perform actions, the request must use an authenticated session.
Access Token ¶
Access to the API is granted in the form of a short-lived access token, which the client must present as bearer token in the Authorization header in each request. A client can obtain an access token by presenting a valid Skalio ID token.
Access tokens follow the JSON Web Token standard and can be analyzed by the client.
| claim | relevance, purpose |
|---|---|
sub |
Contains the UID of the person the token belongs to. |
exp |
Timestamp in epoch-format, when the token is expired and is no longer accepted. |
scope |
Value: access. Can be used to distinguish between tokens. |
http://skalio.com/hostname |
Hostname where the access token is accepted. |
amr |
Optional array claim. Contains the authentication methods used to obtain the ID token. |
An access token is only accepted at the hostname it is intended for.
POST https://free.teambeam.de/api/skp/v2/auth/access?cookie=false
Requests
Scenario where the ID token grants access to the current host.
Headers
Authorization: Bearer {.. ID token ..}Responses
The authentication was successful.
Headers
Content-Type: application/jsonBody
{
"token": "Hello, world!"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "An access token. Encoded JWT according to RFC 7519."
}
},
"required": [
"token"
]
}The ID token was rejected.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Request cannot be fulfilled",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"enum": [
0
],
"description": "unique error code"
},
"message": {
"type": "string",
"enum": [
"Request cannot be fulfilled"
],
"description": "localized error text"
},
"details": {
"type": "array",
"items": {
"type": "string",
"enum": [
""
]
},
"description": "additional localized error messages"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}Access to the adminunit is rejected. Check the details for an explanation.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get access tokenPOST/auth/access?cookie={cookie}
Provide a Skalio ID token and receive a short lived access token to use TeamBeam Transfer.
The backend accepts a valid ID token and issues an access token, even if the person belongs to an adminunit on a different hostname. However, the resulting access token is only valid at the person’s own adminunit.
Requirements:
- The ID token contains claims matching the current adminunit.
- Skalio ID token v3 uses claims
http:/skalio.com/org_idandroles
- Skalio ID token v3 uses claims
The backend will try to find, migrate or auto-create a user matching the ID token:
-
search for user by uid matching
subjectclaim from token -
if not found: search for user by email matching
emailclaim from token- excludes users managed by an LDAP directory
- if found: migrate to “Skalio ID authentication” by setting
uidfield and clearingpasswordHash
-
if not found: auto-create the user as per Skalio ID profile
On the web-platform, it is recommended to request cookie=true. This will deliver the access token as a secure HTTP cookie in addition to the regular payload. A web-browser will then automatically send the cookie for matching requests. This enables downloading of locked or protected files as the authenticated sender or receiver directly within a web-browser.
The cookie is only sent if the user’s adminunit matches the hostname the request arrived on. Cookies cannot be sent for a foreign hostname.
URI Parameters
- cookie
boolean(optional) Example: falseIf true, the access token will also be delivered as a cookie. Default: false.
Sending transfers ¶
The process of sending data uses reservations to bundle multiple requests in a flexible approach:
-
Create a new reservation:
- Upload to a mailbox: preset recipient, does not require authentication
- Person-to-person reservation: requires authentication and authorization, sender can choose (multiple) recipients
- Archive upload: requires authentication, recipient is a folder
-
Update reservation details, if necessary
- Set or change the metadata of a reservation, such as subject, description, time-to-live, etc.
-
Upload payload to the reservation
- Attach none, one or more files to the reservation
- Upload files completely or using upload-resume
- Payload can be removed again
-
Confirm the reservation
- This triggers post-processing, creating individual transfers and notifying the recipients
When a reservation is created, the server returns an access token. This token is specific to the reservation and must be used to authenticate all subsequent requests specific to the reservation. The token has the same validity as the maximum duration of an open reservation. If the reservation is not confirmed within this timeframe, it is removed automatically.
The token can be decoded as a JWT and inspected:
| Claim | Purpose |
|---|---|
scope |
"reservation" |
subject |
uid of the reservation |
exp |
Validity of token and open reservation |
Reservation ¶
POST https://free.teambeam.de/api/skp/v2/reservations
Requests
Headers
Content-Type: application/json
Authorization: Bearer {... access token ...}Body
{
"subject": "Hello, world!",
"description": "Hello, world!",
"deliveryNotification": false,
"ttl": 1,
"priority": 3,
"protection": "none",
"password": "Hello, world!",
"recipients": [
{
"uid": "36odq_1mklfavec7",
"name": "Alice",
"email": "alice@example.org",
"destinationType": "to"
}
],
"folder": 1
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Subject of the new transfer"
},
"description": {
"type": "string",
"description": "Description of the new transfer"
},
"deliveryNotification": {
"type": "boolean",
"description": "If true, the uploader is informed when the new transfer has been accessed"
},
"ttl": {
"type": "number",
"description": "Number of days before the transfer expires. If not yet, the adminunit default is used."
},
"priority": {
"type": "number",
"description": "From highest (1) to lowest (5)"
},
"protection": {
"type": "string",
"enum": [
"none",
"password",
"recipientAuthentication"
],
"description": "Default: `none`"
},
"password": {
"type": "string",
"description": "Required if protection is set to `password`"
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"36odq_1mklfavec7"
],
"description": "UID of the person, if found."
},
"name": {
"type": "string",
"enum": [
"Alice"
],
"description": "Name of the recipient"
},
"email": {
"type": "string",
"enum": [
"alice@example.org"
],
"description": "Email address of recipient"
},
"destinationType": {
"type": "string",
"enum": [
"to",
"cc",
"bcc"
]
}
},
"required": [
"email",
"destinationType"
],
"additionalProperties": false
},
"description": "List of recipients. Can be empty for archive-only- or drop-transfers."
},
"folder": {
"type": "number",
"description": "References a folder of an archive as the destination."
}
},
"required": [
"recipients"
]
}Responses
The reservation has been created.
Headers
Content-Type: application/json
Authorization: Bearer {... reservation-specific access token ...}Body
{
"subject": "Hello, world!",
"description": "Hello, world!",
"deliveryNotification": false,
"ttl": 1,
"priority": 3,
"protection": "none",
"password": "Hello, world!",
"uid": "s528x16vo52j18la0yvv",
"anonSender": "John Doe",
"anonEmail": "john.doe@example.org",
"recipients": [
{
"uid": "36odq_1mklfavec7",
"name": "Alice",
"email": "alice@example.org",
"destinationType": "to"
}
],
"folder": 1,
"objects": [
{
"clientId": "abc123",
"name": "Sales_Forecast.xlsx",
"size": 200000,
"intendedSize": 410339
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Subject of the new transfer"
},
"description": {
"type": "string",
"description": "Description of the new transfer"
},
"deliveryNotification": {
"type": "boolean",
"description": "If true, the uploader is informed when the new transfer has been accessed"
},
"ttl": {
"type": "number",
"description": "Number of days before the transfer expires. If not yet, the adminunit default is used."
},
"priority": {
"type": "number",
"description": "From highest (1) to lowest (5)"
},
"protection": {
"type": "string",
"enum": [
"none",
"password",
"recipientAuthentication"
],
"description": "Default: `none`"
},
"password": {
"type": "string",
"description": "Required if protection is set to `password`"
},
"uid": {
"type": "string",
"description": "Readonly. UID of the reservation"
},
"anonSender": {
"type": "string",
"description": "Name of the uploader. For mailbox transfers, this field is required."
},
"anonEmail": {
"type": "string",
"description": "Email address of the uploader. For mailbox transfers, this field is required."
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"36odq_1mklfavec7"
],
"description": "UID of the person, if found."
},
"name": {
"type": "string",
"enum": [
"Alice"
],
"description": "Name of the recipient"
},
"email": {
"type": "string",
"enum": [
"alice@example.org"
],
"description": "Email address of recipient"
},
"destinationType": {
"type": "string",
"enum": [
"to",
"cc",
"bcc"
]
}
},
"required": [
"email",
"destinationType"
],
"additionalProperties": false
},
"description": "List of recipients. Can be empty for archive-only- or drop-transfers."
},
"folder": {
"type": "number",
"description": "References a folder of an archive as the destination."
},
"objects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientId": {
"type": "string",
"enum": [
"abc123"
],
"description": "A client-set reservation-unique identifier of an object."
},
"name": {
"type": "string",
"enum": [
"Sales_Forecast.xlsx"
],
"description": "The filename of the object."
},
"size": {
"type": "number",
"enum": [
200000
],
"description": "Actual size of the file in number of Bytes."
},
"intendedSize": {
"type": "number",
"enum": [
410339
],
"description": "Expected file size in Bytes."
}
},
"required": [
"clientId",
"name",
"size",
"intendedSize"
],
"additionalProperties": false
},
"description": "Readonly. List of objects that are attached to the reservation."
}
},
"required": [
"uid",
"recipients",
"objects"
]
}Create a reservationPOST/reservations
Initiate a new transfer by creating a reservation. In subsequent steps, add files, update the metadata if necessary, then confirm the reservation.
The response contains a reservation-specific access token in the response header Authorization. The tokenis valid for 48h and authenticates changes to the reservation, file uploads as well as reservation-confirmation. After this time, the reservation expires automatically.
This request must be authenticated with an access token and requires the role Service.Transfer.Use.
Not yet implemented!
GET https://free.teambeam.de/api/skp/v2/reservations/s528x16vo52j18la0yvv
Requests
Headers
Authorization: Bearer {... reservation token ...}Responses
Headers
Content-Type: application/jsonBody
{
"subject": "Hello, world!",
"description": "Hello, world!",
"deliveryNotification": false,
"ttl": 1,
"priority": 3,
"protection": "none",
"password": "Hello, world!",
"uid": "s528x16vo52j18la0yvv",
"anonSender": "John Doe",
"anonEmail": "john.doe@example.org",
"recipients": [
{
"uid": "36odq_1mklfavec7",
"name": "Alice",
"email": "alice@example.org",
"destinationType": "to"
}
],
"folder": 1,
"objects": [
{
"clientId": "abc123",
"name": "Sales_Forecast.xlsx",
"size": 200000,
"intendedSize": 410339
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Subject of the new transfer"
},
"description": {
"type": "string",
"description": "Description of the new transfer"
},
"deliveryNotification": {
"type": "boolean",
"description": "If true, the uploader is informed when the new transfer has been accessed"
},
"ttl": {
"type": "number",
"description": "Number of days before the transfer expires. If not yet, the adminunit default is used."
},
"priority": {
"type": "number",
"description": "From highest (1) to lowest (5)"
},
"protection": {
"type": "string",
"enum": [
"none",
"password",
"recipientAuthentication"
],
"description": "Default: `none`"
},
"password": {
"type": "string",
"description": "Required if protection is set to `password`"
},
"uid": {
"type": "string",
"description": "Readonly. UID of the reservation"
},
"anonSender": {
"type": "string",
"description": "Name of the uploader. For mailbox transfers, this field is required."
},
"anonEmail": {
"type": "string",
"description": "Email address of the uploader. For mailbox transfers, this field is required."
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"36odq_1mklfavec7"
],
"description": "UID of the person, if found."
},
"name": {
"type": "string",
"enum": [
"Alice"
],
"description": "Name of the recipient"
},
"email": {
"type": "string",
"enum": [
"alice@example.org"
],
"description": "Email address of recipient"
},
"destinationType": {
"type": "string",
"enum": [
"to",
"cc",
"bcc"
]
}
},
"required": [
"email",
"destinationType"
],
"additionalProperties": false
},
"description": "List of recipients. Can be empty for archive-only- or drop-transfers."
},
"folder": {
"type": "number",
"description": "References a folder of an archive as the destination."
},
"objects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientId": {
"type": "string",
"enum": [
"abc123"
],
"description": "A client-set reservation-unique identifier of an object."
},
"name": {
"type": "string",
"enum": [
"Sales_Forecast.xlsx"
],
"description": "The filename of the object."
},
"size": {
"type": "number",
"enum": [
200000
],
"description": "Actual size of the file in number of Bytes."
},
"intendedSize": {
"type": "number",
"enum": [
410339
],
"description": "Expected file size in Bytes."
}
},
"required": [
"clientId",
"name",
"size",
"intendedSize"
],
"additionalProperties": false
},
"description": "Readonly. List of objects that are attached to the reservation."
}
},
"required": [
"uid",
"recipients",
"objects"
]
}Reservation not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch a reservationGET/reservations/{uid}
Fetches a reservation.
This request must be authenticated with the reservation-specific access token.
URI Parameters
- uid
string(required) Example: s528x16vo52j18la0yvvUID of the reservation
PUT https://free.teambeam.de/api/skp/v2/reservations/s528x16vo52j18la0yvv
Requests
Update a reservation.
Headers
Authorization: Bearer {... reservation token ...}Body
{
"subject": "Hello, world!",
"description": "Hello, world!",
"deliveryNotification": false,
"ttl": 1,
"priority": 3,
"protection": "none",
"password": "Hello, world!",
"uid": "s528x16vo52j18la0yvv",
"anonSender": "John Doe",
"anonEmail": "john.doe@example.org",
"recipients": [
{
"uid": "36odq_1mklfavec7",
"name": "Alice",
"email": "alice@example.org",
"destinationType": "to"
}
],
"folder": 1,
"objects": [
{
"clientId": "abc123",
"name": "Sales_Forecast.xlsx",
"size": 200000,
"intendedSize": 410339
}
]
}Schema
{
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Subject of the new transfer"
},
"description": {
"type": "string",
"description": "Description of the new transfer"
},
"deliveryNotification": {
"type": "boolean",
"description": "If true, the uploader is informed when the new transfer has been accessed"
},
"ttl": {
"type": "number",
"description": "Number of days before the transfer expires. If not yet, the adminunit default is used."
},
"priority": {
"type": "number",
"description": "From highest (1) to lowest (5)"
},
"protection": {
"enum": [
"none",
"password",
"recipientAuthentication"
],
"description": "Default: `none`"
},
"password": {
"type": "string",
"description": "Required if protection is set to `password`"
},
"uid": {
"type": "string",
"description": "Readonly. UID of the reservation"
},
"anonSender": {
"type": "string",
"description": "Name of the uploader. For mailbox transfers, this field is required."
},
"anonEmail": {
"type": "string",
"description": "Email address of the uploader. For mailbox transfers, this field is required."
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "UID of the person, if found."
},
"name": {
"type": "string",
"description": "Name of the recipient"
},
"email": {
"type": "string",
"description": "Email address of recipient"
},
"destinationType": {
"enum": [
"to",
"cc",
"bcc"
]
}
},
"required": [
"email",
"destinationType"
]
},
"description": "List of recipients. Can be empty for archive-only- or drop-transfers."
},
"folder": {
"type": "number",
"description": "References a folder of an archive as the destination."
},
"objects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientId": {
"type": "string",
"description": "A client-set reservation-unique identifier of an object."
},
"name": {
"type": "string",
"description": "The filename of the object."
},
"size": {
"type": "number",
"description": "Actual size of the file in number of Bytes."
},
"intendedSize": {
"type": "number",
"description": "Expected file size in Bytes."
}
},
"required": [
"clientId",
"name",
"size",
"intendedSize"
]
},
"description": "Readonly. List of objects that are attached to the reservation."
}
},
"required": [
"uid"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Responses
Reservation has been updated.
Headers
Content-Type: application/jsonBody
{
"subject": "Hello, world!",
"description": "Hello, world!",
"deliveryNotification": false,
"ttl": 1,
"priority": 3,
"protection": "none",
"password": "Hello, world!",
"uid": "s528x16vo52j18la0yvv",
"anonSender": "John Doe",
"anonEmail": "john.doe@example.org",
"recipients": [
{
"uid": "36odq_1mklfavec7",
"name": "Alice",
"email": "alice@example.org",
"destinationType": "to"
}
],
"folder": 1,
"objects": [
{
"clientId": "abc123",
"name": "Sales_Forecast.xlsx",
"size": 200000,
"intendedSize": 410339
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Subject of the new transfer"
},
"description": {
"type": "string",
"description": "Description of the new transfer"
},
"deliveryNotification": {
"type": "boolean",
"description": "If true, the uploader is informed when the new transfer has been accessed"
},
"ttl": {
"type": "number",
"description": "Number of days before the transfer expires. If not yet, the adminunit default is used."
},
"priority": {
"type": "number",
"description": "From highest (1) to lowest (5)"
},
"protection": {
"type": "string",
"enum": [
"none",
"password",
"recipientAuthentication"
],
"description": "Default: `none`"
},
"password": {
"type": "string",
"description": "Required if protection is set to `password`"
},
"uid": {
"type": "string",
"description": "Readonly. UID of the reservation"
},
"anonSender": {
"type": "string",
"description": "Name of the uploader. For mailbox transfers, this field is required."
},
"anonEmail": {
"type": "string",
"description": "Email address of the uploader. For mailbox transfers, this field is required."
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"36odq_1mklfavec7"
],
"description": "UID of the person, if found."
},
"name": {
"type": "string",
"enum": [
"Alice"
],
"description": "Name of the recipient"
},
"email": {
"type": "string",
"enum": [
"alice@example.org"
],
"description": "Email address of recipient"
},
"destinationType": {
"type": "string",
"enum": [
"to",
"cc",
"bcc"
]
}
},
"required": [
"email",
"destinationType"
],
"additionalProperties": false
},
"description": "List of recipients. Can be empty for archive-only- or drop-transfers."
},
"folder": {
"type": "number",
"description": "References a folder of an archive as the destination."
},
"objects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientId": {
"type": "string",
"enum": [
"abc123"
],
"description": "A client-set reservation-unique identifier of an object."
},
"name": {
"type": "string",
"enum": [
"Sales_Forecast.xlsx"
],
"description": "The filename of the object."
},
"size": {
"type": "number",
"enum": [
200000
],
"description": "Actual size of the file in number of Bytes."
},
"intendedSize": {
"type": "number",
"enum": [
410339
],
"description": "Expected file size in Bytes."
}
},
"required": [
"clientId",
"name",
"size",
"intendedSize"
],
"additionalProperties": false
},
"description": "Readonly. List of objects that are attached to the reservation."
}
},
"required": [
"uid",
"recipients",
"objects"
]
}Missing field or invalid type or value.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Missing or invalid authentication.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Exceeding a limitation.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Reservation not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update a reservationPUT/reservations/{uid}
Updates metadata of a reservation. Some fields may not be updated depending on the type of reservation:
-
A reservation for a mailbox has a fixed recipient, cannot use a folder but requires
anonSenderandanonEmailfields. -
A person-to-person reservation cannot use
anon-*fields.
This request must be authenticated with the reservation-specific access token.
URI Parameters
- uid
string(required) Example: s528x16vo52j18la0yvvUID of the reservation
POST https://free.teambeam.de/api/skp/v2/reservations/s528x16vo52j18la0yvv/confirm
Requests
Headers
Authorization: Bearer {... reservation token ...}Responses
Headers
Content-Type: application/jsonBody
{
"transfers": [
{
"recipientId": "6sblt7v0xpe0n30ny9u5",
"type": "p2p"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"transfers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipientId": {
"type": "string",
"enum": [
"6sblt7v0xpe0n30ny9u5"
],
"description": "ID of the transfer"
},
"type": {
"type": "string",
"enum": [
"p2p",
"archive",
"mailbox"
]
}
},
"required": [
"recipientId",
"type"
],
"additionalProperties": false
}
}
},
"required": [
"transfers"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Limits exceeded.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Reservation or payload not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Ratelimit exceeded.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The rate limit has been exceeded.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Confirm reservationPOST/reservations/{uid}/confirm
Confirms the reservation and triggers transfer creation. The reservation is automatically removed afterwards and can no longer be modified.
All payload that was attached with upload-resume must be uploaded completely: The actual size must match the advertised size as per the Content-Range header. There must be no ongoing upload.
Before accepting the reservation, it is being checked against server-side limits.
For each recipient and folder of the reservation, an individual transfer is created. The response contains the list of transfers and their transfer IDs.
This request must be authenticated with the reservation-specific access token.
URI Parameters
- uid
string(required) Example: s528x16vo52j18la0yvvUID of the reservation
DELETE https://free.teambeam.de/api/skp/v2/reservations/s528x16vo52j18la0yvv
Requests
Headers
Authorization: Bearer {... reservation token ...}Responses
Headers
Content-Type: application/jsonAuthentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Reservation or payload not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Cancel reservationDELETE/reservations/{uid}
Cancels the reservation and removes all payload.
This request must be authenticated with the reservation-specific access token.
URI Parameters
- uid
string(required) Example: s528x16vo52j18la0yvvUID of the reservation
Payload ¶
POST https://free.teambeam.de/api/skp/v2/reservations/s528x16vo52j18la0yvv/files/abc123
Requests
Upload of a complete file
Headers
Authorization: Bearer {... reservation token ...}
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryvvTtKG8usN46aTrCBody
------WebKitFormBoundaryvvTtKG8usN46aTrC
Content-Disposition: form-data; name="file"; filename="IMG_8613.JPG"
Content-Type: image/jpeg
... payload ...
------WebKitFormBoundaryvvTtKG8usN46aTrC--Responses
This response has no content.
Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Limits exceeded.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Reservation not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Upload of a chunk
Headers
Authorization: Bearer {... reservation token ...}
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryvvTtKG8usN46aTrC
Content-Range: bytes 200000-299999/321452Body
------WebKitFormBoundaryvvTtKG8usN46aTrC
Content-Disposition: form-data; name="file"; filename="IMG_8613.JPG"
Content-Type: image/jpeg
... payload ...
------WebKitFormBoundaryvvTtKG8usN46aTrC--Responses
This response has no content.
Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Limits exceeded.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Reservation not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Range request did not match uploaded payload.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested range could not be statisfied.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Upload payloadPOST/reservations/{uid}/files/{clientId}
Uploads payload-data to the reservation. Supports upload-resume through a Content-Range request header.
-
Clients must use an individual reservation-unique
clientIdto identify the payload. In chunked transfer mode, use it to address the same payload again. -
Clients provide the payload in form-data bodypart named
file, including thefilenameparameter. -
The
Content-Typeheader of the form-data bodypart is ignored; instead the content-type is determined server-side. -
Chunked transfer / upload resume supports only contiguous uploads. Overwrite of existing data or sparse files (with “holes”) is not supported.
-
Concurrent uploads to the same client-ID are not supported.
This request must be authenticated with the reservation-specific access token.
URI Parameters
- uid
string(required) Example: s528x16vo52j18la0yvvUID of the reservation
- clientId
string(required) Example: abc123client-set reservation-unique identifier of the object
HEAD https://free.teambeam.de/api/skp/v2/reservations/s528x16vo52j18la0yvv/files/abc123
Requests
Headers
Authorization: Bearer {... reservation token ...}Responses
Headers
Content-Length: 200000Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Reservation or payload not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Check payloadHEAD/reservations/{uid}/files/{clientId}
Checks the actual size of the uploaded payload.
This request must be authenticated with the reservation-specific access token.
URI Parameters
- uid
string(required) Example: s528x16vo52j18la0yvvUID of the reservation
- clientId
string(required) Example: abc123client-set reservation-unique identifier of the object
DELETE https://free.teambeam.de/api/skp/v2/reservations/s528x16vo52j18la0yvv/files/abc123
Requests
Headers
Authorization: Bearer {... reservation token ...}Responses
This response has no content.
Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Reservation or payload not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Remove payloadDELETE/reservations/{uid}/files/{clientId}
Removes the payload from the reservation.
This request must be authenticated with the reservation-specific access token.
URI Parameters
- uid
string(required) Example: s528x16vo52j18la0yvvUID of the reservation
- clientId
string(required) Example: abc123client-set reservation-unique identifier of the object
Adminunit management ¶
An adminunit is the top level entity that combines users, transfers, folders, objects, etc. representing a customer.
All requests must be authenticated with an access token. Administrator privileges are required.
Adminunit ¶
GET https://free.teambeam.de/api/skp/v2/adminunit
Requests
Headers
Authorization: Bearer {... access token ...}Responses
Headers
Content-Type: application/jsonBody
{
"uid": "zt8khx5u.hotnvdm",
"customerName": "'Example Org'",
"defaultExpiration": 7,
"expirationIntervals": [
3,
5,
7
],
"allowCustomExpiration": true,
"forcedMalwareCheck": true,
"forcedPasswordUsage": false,
"blockAfterFirstDownload": false,
"forcedRecipientAuthentication": false
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
},
"customerName": {
"type": "string",
"description": "Organization name, readonly."
},
"defaultExpiration": {
"type": "number",
"description": "Default expiration of a new transfer, in days."
},
"expirationIntervals": {
"type": "array",
"description": "List of expiration intervals that can be used, in days."
},
"allowCustomExpiration": {
"type": "boolean",
"description": "Allows the user to chose from the expiration intervals or always use the default value."
},
"forcedMalwareCheck": {
"type": "boolean",
"description": "Send all new transfers through malware check."
},
"forcedPasswordUsage": {
"type": "boolean",
"description": "Require that all new transfers have a password."
},
"blockAfterFirstDownload": {
"type": "boolean",
"description": "Require that all new transfers can be downloaded only once."
},
"forcedRecipientAuthentication": {
"type": "boolean",
"description": "Require that all new transfers use recipient authentication."
}
},
"required": [
"uid",
"customerName",
"defaultExpiration",
"expirationIntervals",
"allowCustomExpiration",
"forcedMalwareCheck",
"forcedPasswordUsage",
"blockAfterFirstDownload",
"forcedRecipientAuthentication"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access to this adminunit has been denied.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}PUT https://free.teambeam.de/api/skp/v2/adminunit
Requests
Headers
Content-Type: application/json
Authorization: Bearer {... access token ...}Body
{
"uid": "zt8khx5u.hotnvdm",
"customerName": "'Example Org'",
"defaultExpiration": 7,
"expirationIntervals": [
3,
5,
7
],
"allowCustomExpiration": true,
"forcedMalwareCheck": true,
"forcedPasswordUsage": false,
"blockAfterFirstDownload": false,
"forcedRecipientAuthentication": false
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
},
"customerName": {
"type": "string",
"description": "Organization name, readonly."
},
"defaultExpiration": {
"type": "number",
"description": "Default expiration of a new transfer, in days."
},
"expirationIntervals": {
"type": "array",
"description": "List of expiration intervals that can be used, in days."
},
"allowCustomExpiration": {
"type": "boolean",
"description": "Allows the user to chose from the expiration intervals or always use the default value."
},
"forcedMalwareCheck": {
"type": "boolean",
"description": "Send all new transfers through malware check."
},
"forcedPasswordUsage": {
"type": "boolean",
"description": "Require that all new transfers have a password."
},
"blockAfterFirstDownload": {
"type": "boolean",
"description": "Require that all new transfers can be downloaded only once."
},
"forcedRecipientAuthentication": {
"type": "boolean",
"description": "Require that all new transfers use recipient authentication."
}
},
"required": [
"uid",
"customerName",
"defaultExpiration",
"expirationIntervals",
"allowCustomExpiration",
"forcedMalwareCheck",
"forcedPasswordUsage",
"blockAfterFirstDownload",
"forcedRecipientAuthentication"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"uid": "zt8khx5u.hotnvdm",
"customerName": "'Example Org'",
"defaultExpiration": 7,
"expirationIntervals": [
3,
5,
7
],
"allowCustomExpiration": true,
"forcedMalwareCheck": true,
"forcedPasswordUsage": false,
"blockAfterFirstDownload": false,
"forcedRecipientAuthentication": false
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
},
"customerName": {
"type": "string",
"description": "Organization name, readonly."
},
"defaultExpiration": {
"type": "number",
"description": "Default expiration of a new transfer, in days."
},
"expirationIntervals": {
"type": "array",
"description": "List of expiration intervals that can be used, in days."
},
"allowCustomExpiration": {
"type": "boolean",
"description": "Allows the user to chose from the expiration intervals or always use the default value."
},
"forcedMalwareCheck": {
"type": "boolean",
"description": "Send all new transfers through malware check."
},
"forcedPasswordUsage": {
"type": "boolean",
"description": "Require that all new transfers have a password."
},
"blockAfterFirstDownload": {
"type": "boolean",
"description": "Require that all new transfers can be downloaded only once."
},
"forcedRecipientAuthentication": {
"type": "boolean",
"description": "Require that all new transfers use recipient authentication."
}
},
"required": [
"uid",
"customerName",
"defaultExpiration",
"expirationIntervals",
"allowCustomExpiration",
"forcedMalwareCheck",
"forcedPasswordUsage",
"blockAfterFirstDownload",
"forcedRecipientAuthentication"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access to this adminunit has been denied.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Report settings ¶
The adminunit can create different reports:
-
accounting report: creates a list of users who have used TeamBeam Transfer within the configured reporting period. The report is sent via email to the list of registered addresses.
-
archive root folder report: creates a report of all archive root folders and their total storage size. The report is sent via email to the list of registered addresses.
-
transaction log: a detailed, technical log of TeamBeam Transfer transactions. The data is collected in CSV files and stored in the archive.
GET https://free.teambeam.de/api/skp/v2/adminunit/reports
Requests
Headers
Authorization: Bearer {... access token ...}Responses
Headers
Content-Type: application/jsonBody
{
"accountingReportReceivers": [
"bob@example.test"
],
"accountingReportTime": 1,
"rootFolderReportReceivers": [
"alice@example.test"
],
"transactionLogEnabled": false,
"accountingReportEnabled": true,
"rootFolderReportEnabled": true
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"accountingReportReceivers": {
"type": "array",
"description": "List of email addresses that receive the accounting report. An empty array disables the report."
},
"accountingReportTime": {
"type": "number",
"description": "Defines the number of months that the accounting report covers. Valid values: 1, 3."
},
"rootFolderReportReceivers": {
"type": "array",
"description": "List of email addresses that receive the archive root-folder report. An empty array disables the report."
},
"transactionLogEnabled": {
"type": "boolean",
"description": "Controls recording of transaction log events."
},
"accountingReportEnabled": {
"type": "boolean",
"description": "Shows if the accounting report is enabled, readonly."
},
"rootFolderReportEnabled": {
"type": "boolean",
"description": "Shows if the archive root-folder report is enabled, readonly."
}
},
"required": [
"accountingReportReceivers",
"accountingReportTime",
"rootFolderReportReceivers",
"transactionLogEnabled",
"accountingReportEnabled",
"rootFolderReportEnabled"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access to this adminunit has been denied.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch settingsGET/adminunit/reports
Returns the reports settings for the adminunit.
This request requires admin privileges.
PUT https://free.teambeam.de/api/skp/v2/adminunit/reports
Requests
Headers
Content-Type: application/json
Authorization: Bearer {... access token ...}Body
{
"accountingReportReceivers": [
"bob@example.test"
],
"accountingReportTime": 1,
"rootFolderReportReceivers": [
"alice@example.test"
],
"transactionLogEnabled": false
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"accountingReportReceivers": {
"type": "array",
"description": "List of email addresses that receive the accounting report. An empty array disables the report."
},
"accountingReportTime": {
"type": "number",
"description": "Defines the number of months that the accounting report covers. Valid values: 1, 3."
},
"rootFolderReportReceivers": {
"type": "array",
"description": "List of email addresses that receive the archive root-folder report. An empty array disables the report."
},
"transactionLogEnabled": {
"type": "boolean",
"description": "Controls recording of transaction log events."
}
},
"required": [
"accountingReportReceivers",
"accountingReportTime",
"rootFolderReportReceivers",
"transactionLogEnabled"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"accountingReportReceivers": [
"bob@example.test"
],
"accountingReportTime": 1,
"rootFolderReportReceivers": [
"alice@example.test"
],
"transactionLogEnabled": false,
"accountingReportEnabled": true,
"rootFolderReportEnabled": true
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"accountingReportReceivers": {
"type": "array",
"description": "List of email addresses that receive the accounting report. An empty array disables the report."
},
"accountingReportTime": {
"type": "number",
"description": "Defines the number of months that the accounting report covers. Valid values: 1, 3."
},
"rootFolderReportReceivers": {
"type": "array",
"description": "List of email addresses that receive the archive root-folder report. An empty array disables the report."
},
"transactionLogEnabled": {
"type": "boolean",
"description": "Controls recording of transaction log events."
},
"accountingReportEnabled": {
"type": "boolean",
"description": "Shows if the accounting report is enabled, readonly."
},
"rootFolderReportEnabled": {
"type": "boolean",
"description": "Shows if the archive root-folder report is enabled, readonly."
}
},
"required": [
"accountingReportReceivers",
"accountingReportTime",
"rootFolderReportReceivers",
"transactionLogEnabled",
"accountingReportEnabled",
"rootFolderReportEnabled"
]
}Data was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access to this adminunit has been denied.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update settingsPUT/adminunit/reports
Updates the reports settings for the adminunit.
To enable the accounting report or the archive root-folder report, a list of recipient email addresses has to be set. If the list of addresses is empty, the report is disabled.
Valid values for accountReportTime is 1 or 3 (months).
This request requires admin privileges.
Preset settings ¶
When a new user is first created as a member of the adminunit, the values from this preset are applied to the user. Afterwards the user can change the settings for themselves.
GET https://free.teambeam.de/api/skp/v2/adminunit/preset
Requests
Headers
Authorization: Bearer {... access token ...}Responses
Headers
Content-Type: application/jsonBody
{
"expiryWarningEnabled": true,
"uploadConfirmationEnabled": true
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"expiryWarningEnabled": {
"type": "boolean",
"description": "If true, the user will be notified of expiring transfers."
},
"uploadConfirmationEnabled": {
"type": "boolean",
"description": "If true, the user will be notified after a transfer has been uploaded successfully."
}
},
"required": [
"expiryWarningEnabled",
"uploadConfirmationEnabled"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access to this adminunit has been denied.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch presetGET/adminunit/preset
Returns the preset for the adminunit.
This request requires admin privileges.
PUT https://free.teambeam.de/api/skp/v2/adminunit/preset
Requests
Headers
Content-Type: application/json
Authorization: Bearer {... access token ...}Body
{
"expiryWarningEnabled": true,
"uploadConfirmationEnabled": true
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"expiryWarningEnabled": {
"type": "boolean",
"description": "If true, the user will be notified of expiring transfers."
},
"uploadConfirmationEnabled": {
"type": "boolean",
"description": "If true, the user will be notified after a transfer has been uploaded successfully."
}
},
"required": [
"expiryWarningEnabled",
"uploadConfirmationEnabled"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"expiryWarningEnabled": true,
"uploadConfirmationEnabled": true
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"expiryWarningEnabled": {
"type": "boolean",
"description": "If true, the user will be notified of expiring transfers."
},
"uploadConfirmationEnabled": {
"type": "boolean",
"description": "If true, the user will be notified after a transfer has been uploaded successfully."
}
},
"required": [
"expiryWarningEnabled",
"uploadConfirmationEnabled"
]
}Data was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access to this adminunit has been denied.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update presetPUT/adminunit/preset
Updates the preset settings, to apply to future users.
This request requires admin privileges.
Role settings ¶
All users and mailboxes are assigned the default role. The privileges defined here apply to all users of the adminunit and their mailboxes.
| privilege | type | description |
|---|---|---|
canUsePersonalArchive |
boolean | Controls if the user can store new transfers in their personal archive. |
personalArchiveQuotaMb |
number, 0 … 2.000.000 | Maximum storage space for transfers in the personal archive, in megabyte. A value of 0 disables this limit. |
transferUploadQuotaMb |
number, 0 … 2.000.000 | Maximum monthly upload volume for transfers, per person, in megabyte. A value of 0 disables this limit. |
transferMaxFileSizeMb |
number, 1 … 2.000.000 | Maximum size of a each file or a person-to-person transfer. |
transferMaxFiles |
number, 1 … 300 | Maximum number of files of a person-to-person transfer. |
transferMaxRecipients |
number, 1 … 2.000 | Maximum number of recipients of a person-to-person transfer. |
mailboxMaxFileSizeMb |
number, 1 … 2.000.000 | Maximum size of a each file of a mailbox transfer. |
mailboxMaxFiles |
number, 1 … 300 | Maximum number of files of a mailboxMaxFiles transfer. |
GET https://free.teambeam.de/api/skp/v2/adminunit/role
Requests
Headers
Authorization: Bearer {... access token ...}Responses
Headers
Content-Type: application/jsonBody
{
"name": "Standard role",
"canUsePersonalArchive": true,
"personalArchiveQuotaMb": 1000,
"transferUploadQuotaMb": 1000,
"transferMaxFileSizeMb": 1000,
"transferMaxFiles": 300,
"transferMaxRecipients": 100,
"mailboxMaxFileSizeMb": 1000,
"mailboxMaxFiles": 300
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The role name."
},
"canUsePersonalArchive": {
"type": "boolean",
"description": "Controls if users can store transfers in their personal archive."
},
"personalArchiveQuotaMb": {
"type": "number",
"description": "Maximum total storage spaces of the personal archive. A value of 0 removes the limit."
},
"transferUploadQuotaMb": {
"type": "number",
"description": "Maximum total upload volume per user per month. A value of 0 removes the limit."
},
"transferMaxFileSizeMb": {
"type": "number",
"description": "Maximum size of a each file in a person-to-person transfer."
},
"transferMaxFiles": {
"type": "number",
"description": "Maximum number of files of a person-to-person transfer."
},
"transferMaxRecipients": {
"type": "number",
"description": "Maximum number of recipients of a person-to-person transfer."
},
"mailboxMaxFileSizeMb": {
"type": "number",
"description": "Maximum size of a each file in a mailbox transfer."
},
"mailboxMaxFiles": {
"type": "number",
"description": "Maximum number of files of a mailbox transfer."
}
},
"required": [
"name",
"canUsePersonalArchive",
"personalArchiveQuotaMb",
"transferUploadQuotaMb",
"transferMaxFileSizeMb",
"transferMaxFiles",
"transferMaxRecipients",
"mailboxMaxFileSizeMb",
"mailboxMaxFiles"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access to this adminunit has been denied.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch roleGET/adminunit/role
Returns the default role for the adminunit.
This request requires admin privileges.
PUT https://free.teambeam.de/api/skp/v2/adminunit/role
Requests
Headers
Content-Type: application/json
Authorization: Bearer {... access token ...}Body
{
"name": "Standard role",
"canUsePersonalArchive": true,
"personalArchiveQuotaMb": 1000,
"transferUploadQuotaMb": 1000,
"transferMaxFileSizeMb": 1000,
"transferMaxFiles": 300,
"transferMaxRecipients": 100,
"mailboxMaxFileSizeMb": 1000,
"mailboxMaxFiles": 300
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The role name."
},
"canUsePersonalArchive": {
"type": "boolean",
"description": "Controls if users can store transfers in their personal archive."
},
"personalArchiveQuotaMb": {
"type": "number",
"description": "Maximum total storage spaces of the personal archive. A value of 0 removes the limit."
},
"transferUploadQuotaMb": {
"type": "number",
"description": "Maximum total upload volume per user per month. A value of 0 removes the limit."
},
"transferMaxFileSizeMb": {
"type": "number",
"description": "Maximum size of a each file in a person-to-person transfer."
},
"transferMaxFiles": {
"type": "number",
"description": "Maximum number of files of a person-to-person transfer."
},
"transferMaxRecipients": {
"type": "number",
"description": "Maximum number of recipients of a person-to-person transfer."
},
"mailboxMaxFileSizeMb": {
"type": "number",
"description": "Maximum size of a each file in a mailbox transfer."
},
"mailboxMaxFiles": {
"type": "number",
"description": "Maximum number of files of a mailbox transfer."
}
},
"required": [
"name",
"canUsePersonalArchive",
"personalArchiveQuotaMb",
"transferUploadQuotaMb",
"transferMaxFileSizeMb",
"transferMaxFiles",
"transferMaxRecipients",
"mailboxMaxFileSizeMb",
"mailboxMaxFiles"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"name": "Standard role",
"canUsePersonalArchive": true,
"personalArchiveQuotaMb": 1000,
"transferUploadQuotaMb": 1000,
"transferMaxFileSizeMb": 1000,
"transferMaxFiles": 300,
"transferMaxRecipients": 100,
"mailboxMaxFileSizeMb": 1000,
"mailboxMaxFiles": 300
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The role name."
},
"canUsePersonalArchive": {
"type": "boolean",
"description": "Controls if users can store transfers in their personal archive."
},
"personalArchiveQuotaMb": {
"type": "number",
"description": "Maximum total storage spaces of the personal archive. A value of 0 removes the limit."
},
"transferUploadQuotaMb": {
"type": "number",
"description": "Maximum total upload volume per user per month. A value of 0 removes the limit."
},
"transferMaxFileSizeMb": {
"type": "number",
"description": "Maximum size of a each file in a person-to-person transfer."
},
"transferMaxFiles": {
"type": "number",
"description": "Maximum number of files of a person-to-person transfer."
},
"transferMaxRecipients": {
"type": "number",
"description": "Maximum number of recipients of a person-to-person transfer."
},
"mailboxMaxFileSizeMb": {
"type": "number",
"description": "Maximum size of a each file in a mailbox transfer."
},
"mailboxMaxFiles": {
"type": "number",
"description": "Maximum number of files of a mailbox transfer."
}
},
"required": [
"name",
"canUsePersonalArchive",
"personalArchiveQuotaMb",
"transferUploadQuotaMb",
"transferMaxFileSizeMb",
"transferMaxFiles",
"transferMaxRecipients",
"mailboxMaxFileSizeMb",
"mailboxMaxFiles"
]
}Data was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access to this adminunit has been denied.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update rolePUT/adminunit/role
Updates the default role. Changes apply to all users.
This request requires admin privileges.
Mailbox management ¶
A mailbox provides an unauthenticated transfer channel to a user. The sender only needs to know the URL of the mailbox to send a transfer. The transfer consumed quota of the user.
Mailbox groups are a collection of mailboxes. A mailbox group is also access via a URL.
Vanity links ¶
The mailbox and mailbox group URLs can contain an easy-to-remember name, set by the user. This is called the “vanity link”. It must follow these requirements:
-
1…60 characters long
-
unique within the organization / adminunit
-
at least one alphabetic character
-
only uses supported alphabet:
[a-zA-Z0-9+-_.@]
The vanity links of users and mailbox groups are independent of each other. Vanity links are stored case sensitive but evaluated case insensitive.
Mailboxes ¶
An individual mailbox belongs to a user and is identified by the user’s uid.
All requests must be authenticated with an access token. Administrator privileges are required to manage the mailbox of other users.
GET https://free.teambeam.de/api/skp/v2/mailboxes/s_xm0g7br4lpoq5d
Requests
Headers
Authorization: Bearer {... access token ...}Responses
Headers
Content-Type: application/jsonBody
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"description": "Name of the person"
},
"email": {
"type": "string",
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Admin privileges missing in order to manage other person’s mailbox.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Mailbox not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch mailboxGET/mailboxes/{uid}
Fetches the mailbox of a user.
Using keyword me as the UID returns the mailbox of the current principal. This is equivalent of using the uid of the principal.
This request must be authenticated with an access token. Requires admin privileges if the principal and subject don’t match.
URI Parameters
- uid
string(required) Example: s_xm0g7br4lpoq5dUnique identifier of person
PUT https://free.teambeam.de/api/skp/v2/mailboxes/s_xm0g7br4lpoq5d
Requests
Headers
Authorization: Bearer {... access token ...}Body
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}Schema
{
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"description": "Name of the person"
},
"email": {
"type": "string",
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Responses
Headers
Content-Type: application/jsonBody
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"description": "Name of the person"
},
"email": {
"type": "string",
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
]
}A field is missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Admin privileges missing in order to manage other person’s mailbox.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Mailbox not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The vanity link is in use already.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update mailboxPUT/mailboxes/{uid}
Updates an existing mailbox. These fields can be updated:
vanityLink
Using keyword me as the UID returns the mailbox of the current principal. This is equivalent of using the uid of the principal.
Requirements:
- The vanity link must be valid and must not be used by other mailbox groups of the adminunit.
This request must be authenticated with an access token. Requires admin privileges if the principal and subject don’t match.
URI Parameters
- uid
string(required) Example: s_xm0g7br4lpoq5dUnique identifier of person
Mailbox groups ¶
Mailbox groups provide access to multiple individual mailboxes under a single vanity link. Administrators can manage them.
All requests must be authenticated with an access token. Administrator privileges are required.
GET https://free.teambeam.de/api/skp/v2/mailboxgroups
Requests
Headers
Authorization: Bearer {... access token ...}Responses
Headers
Content-Type: application/jsonBody
{
"mailboxgroups": [
{
"name": "Sales Team east",
"description": "Direct mailbox for the sales team",
"vanityLink": "sales_east",
"mailboxes": [
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}
],
"uid": "ffo8csxbftm.enef"
}
],
"total": 1
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"mailboxgroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"enum": [
"Sales Team east"
],
"description": "Name of the person"
},
"description": {
"type": "string",
"enum": [
"Direct mailbox for the sales team"
],
"description": "Optional description of the mailbox"
},
"vanityLink": {
"type": "string",
"enum": [
"sales_east"
],
"description": "Vanity link to the mailbox"
},
"mailboxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"s_xm0g7br4lpoq5d"
],
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"enum": [
"John Doe"
],
"description": "Name of the person"
},
"email": {
"type": "string",
"enum": [
"john@example.org"
],
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"enum": [
"john.doe"
],
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
],
"additionalProperties": false
},
"description": "List of mailboxes in the group"
},
"uid": {
"type": "string",
"enum": [
"ffo8csxbftm.enef"
],
"description": "Unique identifier, readonly."
}
},
"required": [
"name",
"vanityLink",
"mailboxes",
"uid"
],
"additionalProperties": false
},
"description": "List of mailbox groups"
},
"total": {
"type": "number",
"description": "Number of entries in the list"
}
},
"required": [
"mailboxgroups",
"total"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Admin privileges missing.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}List all groupsGET/mailboxgroups
Returns a list of all mailbox groups of the adminunit.
This request must be authenticated with an access token and requires admin privileges.
POST https://free.teambeam.de/api/skp/v2/mailboxgroups
Requests
Headers
Authorization: Bearer {... access token ...}Body
{
"name": "Sales Team east",
"description": "Direct mailbox for the sales team",
"vanityLink": "sales_east",
"mailboxes": [
{
"uid": "s_xm0g7br4lpoq5d"
}
]
}Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the person"
},
"description": {
"type": "string",
"description": "Optional description of the mailbox"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
},
"mailboxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
}
},
"required": [
"uid"
]
},
"description": "List of mailboxes in the group"
}
},
"required": [
"name",
"vanityLink"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Responses
Headers
Content-Type: application/jsonBody
{
"name": "Sales Team east",
"description": "Direct mailbox for the sales team",
"vanityLink": "sales_east",
"mailboxes": [
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}
],
"uid": "ffo8csxbftm.enef"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the person"
},
"description": {
"type": "string",
"description": "Optional description of the mailbox"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
},
"mailboxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"s_xm0g7br4lpoq5d"
],
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"enum": [
"John Doe"
],
"description": "Name of the person"
},
"email": {
"type": "string",
"enum": [
"john@example.org"
],
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"enum": [
"john.doe"
],
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
],
"additionalProperties": false
},
"description": "List of mailboxes in the group"
},
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
}
},
"required": [
"name",
"vanityLink",
"mailboxes",
"uid"
]
}A field is missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Admin privileges missing.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}A referenced user does not exist or does not belong to the adminunit. The vanity link is in use already.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Create groupPOST/mailboxgroups
Creates a new mailbox group. Requirements:
-
A mailbox group must have a valid and unique vanity link.
-
The referenced users must exist and belong to the adminunit. They are referenced by their
uid.
This request must be authenticated with an access token and requires admin privileges.
GET https://free.teambeam.de/api/skp/v2/mailboxgroups/ffo8csxbftm.enef
Requests
Headers
Authorization: Bearer {... access token ...}Responses
Headers
Content-Type: application/jsonBody
{
"name": "Sales Team east",
"description": "Direct mailbox for the sales team",
"vanityLink": "sales_east",
"mailboxes": [
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}
],
"uid": "ffo8csxbftm.enef"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the person"
},
"description": {
"type": "string",
"description": "Optional description of the mailbox"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
},
"mailboxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"s_xm0g7br4lpoq5d"
],
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"enum": [
"John Doe"
],
"description": "Name of the person"
},
"email": {
"type": "string",
"enum": [
"john@example.org"
],
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"enum": [
"john.doe"
],
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
],
"additionalProperties": false
},
"description": "List of mailboxes in the group"
},
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
}
},
"required": [
"name",
"vanityLink",
"mailboxes",
"uid"
]
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Admin privileges missing.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Mailbox not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch groupGET/mailboxgroups/{uid}
Fetches a mailbox group.
This request must be authenticated with an access token and requires admin privileges.
URI Parameters
- uid
string(required) Example: ffo8csxbftm.enefUnique identifier, readonly
PUT https://free.teambeam.de/api/skp/v2/mailboxgroups/ffo8csxbftm.enef
Requests
Headers
Authorization: Bearer {... access token ...}Body
{
"name": "Sales Team east",
"description": "Direct mailbox for the sales team",
"vanityLink": "sales_east",
"mailboxes": [
{
"uid": "s_xm0g7br4lpoq5d"
}
]
}Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the person"
},
"description": {
"type": "string",
"description": "Optional description of the mailbox"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
},
"mailboxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
}
},
"required": [
"uid"
]
},
"description": "List of mailboxes in the group"
}
},
"required": [
"name",
"vanityLink"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Responses
Headers
Content-Type: application/jsonBody
{
"name": "Sales Team east",
"description": "Direct mailbox for the sales team",
"vanityLink": "sales_east",
"mailboxes": [
{
"uid": "s_xm0g7br4lpoq5d",
"name": "John Doe",
"email": "john@example.org",
"vanityLink": "john.doe"
}
],
"uid": "ffo8csxbftm.enef"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the person"
},
"description": {
"type": "string",
"description": "Optional description of the mailbox"
},
"vanityLink": {
"type": "string",
"description": "Vanity link to the mailbox"
},
"mailboxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"s_xm0g7br4lpoq5d"
],
"description": "Unique identifier, readonly."
},
"name": {
"type": "string",
"enum": [
"John Doe"
],
"description": "Name of the person"
},
"email": {
"type": "string",
"enum": [
"john@example.org"
],
"description": "Email address of the person"
},
"vanityLink": {
"type": "string",
"enum": [
"john.doe"
],
"description": "Vanity link to the mailbox"
}
},
"required": [
"uid",
"email"
],
"additionalProperties": false
},
"description": "List of mailboxes in the group"
},
"uid": {
"type": "string",
"description": "Unique identifier, readonly."
}
},
"required": [
"name",
"vanityLink",
"mailboxes",
"uid"
]
}A field is missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Admin privileges missing.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Mailbox not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}A referenced user does not exist or does not belong to the adminunit. The vanity link is in use already.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update groupPUT/mailboxgroups/{uid}
Updates an existing mailbox group. These fields can be updated:
-
name -
description -
vanityLink -
mailboxes
Requirements:
-
A mailbox group must have a valid and unique vanity link
-
The referenced users must exist and belong to the adminunit. They are referenced by their
uid.
This request must be authenticated with an access token and requires admin privileges.
URI Parameters
- uid
string(required) Example: ffo8csxbftm.enefUnique identifier, readonly
DELETE https://free.teambeam.de/api/skp/v2/mailboxgroups/ffo8csxbftm.enef
Requests
Headers
Authorization: Bearer {... access token ...}Responses
This response has no content.
Authentication was missing or invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Admin privileges missing.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Mailbox not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Remove groupDELETE/mailboxgroups/{uid}
Removes a mailbox group.
This request must be authenticated with an access token and requires admin privileges.
URI Parameters
- uid
string(required) Example: ffo8csxbftm.enefUnique identifier, readonly
Generated by aglio on 26 Jun 2025