Vendors API documentation version v1
https://github.com/folio-org/mod-vendors
Emails
CRUD APIs used to manage emails.
/vendor-storage/emails
Collection of email items.
Get list of emails
Create a new email item.
get /vendor-storage/emails
Get list of emails
Query Parameters
- query: (string)
A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.
with valid searchable fields: for example code
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode ["code", "MEDGRANT", "="]
- offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
Skip over a number of elements by specifying an offset value for the query
Example:
0
- limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
Limit the number of elements returned in the response
Example:
10
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
HTTP status code 200
Returns a list of email items
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "collection of email records",
"type": "object",
"properties": {
"emails": {
"description": "The list of emails in this collection",
"type": "array",
"id": "emails",
"items": {
"type": "object",
"$ref": "email.json"
}
},
"total_records": {
"description": "The number of email records returned in this collection",
"type": "integer"
},
"first": {
"description": "The index of the first object in the collection",
"type": "integer"
},
"last": {
"description": "The index of the last object in the collection",
"type": "integer"
}
},
"additionalProperties": false,
"required": [
"emails",
"total_records"
]
}
Example:
{
"emails": [
{
"id": "588b5c42-8634-4af7-bc9b-5e0116ed96b6",
"value": "noreply@folio.org",
"description": "Main"
}
],
"total_records": 1,
"first": 1,
"last": 1
}
HTTP status code 400
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Body
Media type: text/plain
Type: any
Example:
unable to list emails -- malformed parameter 'query', syntax error at column 6
HTTP status code 401
Not authorized to perform requested action
Body
Media type: text/plain
Type: any
Example:
unable to list emails -- unauthorized
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
post /vendor-storage/emails
Create a new email item.
Query Parameters
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "An email record",
"type": "object",
"properties": {
"id": {
"type": ["string", "null"],
"description": "UUID",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"value": {
"description": "The value for this email",
"type": "string"
},
"description": {
"description": "The description for this email",
"type": "string"
},
"isPrimary": {
"description": "Used to set this email as primary for the contact",
"type": "boolean"
},
"categories": {
"id": "categories",
"description": "The list of categories for this vendor email",
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"description": "The language for this vendor email",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"value"
]
}
Example:
{
"value": "noreply@folio.org",
"description": "Main"
}
HTTP status code 201
Returns a newly created item, with server-controlled fields like 'id' populated
Headers
- Location: required (string)
URI to the created email item
Body
Media type: application/json
Type: any
Example:
{
"value": "noreply@folio.org",
"description": "Main"
}
HTTP status code 400
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Body
Media type: text/plain
Type: any
Example:
"unable to add email -- malformed JSON at 13:3"
HTTP status code 401
Not authorized to perform requested action
Body
Media type: text/plain
Type: any
Example:
unable to create emails -- unauthorized
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Entity representing a email
Retrieve email item with given {emailId}
Delete email item with given {emailId}
Update email item with given {emailId}
get /vendor-storage/emails/{id}
Retrieve email item with given {emailId}
URI Parameters
- id: required (string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
The UUID of a Email
Query Parameters
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
HTTP status code 200
Returns item with a given ID
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "An email record",
"type": "object",
"properties": {
"id": {
"type": ["string", "null"],
"description": "UUID",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"value": {
"description": "The value for this email",
"type": "string"
},
"description": {
"description": "The description for this email",
"type": "string"
},
"isPrimary": {
"description": "Used to set this email as primary for the contact",
"type": "boolean"
},
"categories": {
"id": "categories",
"description": "The list of categories for this vendor email",
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"description": "The language for this vendor email",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"value"
]
}
Example:
{
"id": "588b5c42-8634-4af7-bc9b-5e0116ed96b6",
"value": "noreply@folio.org",
"description": "Main"
}
HTTP status code 404
Item with a given ID not found
Body
Media type: text/plain
Type: any
Example:
"email not found"
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
delete /vendor-storage/emails/{id}
Delete email item with given {emailId}
URI Parameters
- id: required (string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
The UUID of a Email
Query Parameters
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
HTTP status code 204
Item deleted successfully
HTTP status code 400
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Body
Media type: text/plain
Type: any
Example:
"unable to delete email -- constraint violation"
HTTP status code 404
Item with a given ID not found
Body
Media type: text/plain
Type: any
Example:
"email not found"
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
put /vendor-storage/emails/{id}
Update email item with given {emailId}
URI Parameters
- id: required (string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
The UUID of a Email
Query Parameters
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "An email record",
"type": "object",
"properties": {
"id": {
"type": ["string", "null"],
"description": "UUID",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"value": {
"description": "The value for this email",
"type": "string"
},
"description": {
"description": "The description for this email",
"type": "string"
},
"isPrimary": {
"description": "Used to set this email as primary for the contact",
"type": "boolean"
},
"categories": {
"id": "categories",
"description": "The list of categories for this vendor email",
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"description": "The language for this vendor email",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"value"
]
}
Example:
{
"id": "588b5c42-8634-4af7-bc9b-5e0116ed96b6",
"value": "noreply@folio.org",
"description": "Main"
}
HTTP status code 204
Item successfully updated
HTTP status code 400
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Body
Media type: text/plain
Type: any
Example:
"unable to update email -- malformed JSON at 13:4"
HTTP status code 404
Item with a given ID not found
Body
Media type: text/plain
Type: any
Example:
"email not found"
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
internal server error, contact administrator