{ "openapi": "3.0.3", "info": { "title": "Transactional Email API", "version": "1.0.0", "description": "" }, "servers": [ { "url": "https://mail-de.retarus.com/rest/v2", "description": "" } ], "security": [ { "httpBasicAuth": [] } ], "tags": [ { "name": "mail", "description": "" } ], "paths": { "/jobs": { "post": { "tags": [ "mail" ], "description": "", "operationId": "sendJobRequest", "requestBody": { "description": "JobRequest - Full Example", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailJobRequest" }, "examples": { "minimal": { "$ref": "#/components/examples/EmailJobMinimalRequest" }, "example": { "$ref": "#/components/examples/EmailJobExampleRequest" }, "complete": { "$ref": "#/components/examples/EmailJobCompleteRequest" } } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseAccepted" }, "examples": { "accepted": { "$ref": "#/components/examples/ResponseAccepted" }, "partial": { "$ref": "#/components/examples/ResponseAcceptedPart" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRejected" }, "example": { "meta": { "jobId": "7fd6ec7a-194e-43d4-b54f-19312bb4124d", "state": { "type": "REJECTED", "subType": "INVALID_VALUE", "phase": "PRE_PROCESS", "description": "Invalid value for mail.from" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRejected" }, "example": { "meta": { "jobId": "8764f6fd-7227-40f8-b242-ff21d02845e9", "state": { "type": "REJECTED", "subType": "FORBIDDEN_SENDER", "phase": "PRE_PROCESS", "description": "Unsupported value for mail.from domain - senderDomain not in configured/allowed domains" } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseRejected" }, "example": { "meta": { "jobId": "7fd6ec7a-194e-43d4-b54f-19312bb4124d", "state": { "type": "REJECTED", "subType": "LIMIT_EXCEEDED", "phase": "PRE_PROCESS", "description": "Request rate limit per hour exceeded." } } } } } } } } } }, "components": { "securitySchemes": { "httpBasicAuth": { "type": "http", "scheme": "basic", "description": "Basic authorization\n" } }, "schemas": { "EmailJobRequest": { "type": "object", "required": [ "mail", "recipients", "subject" ], "properties": { "mail": { "$ref": "#/components/schemas/Mail" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "minItems": 1, "maxItems": 100 }, "subject": { "$ref": "#/components/schemas/Subject" }, "body": { "$ref": "#/components/schemas/Body" }, "alternative": { "$ref": "#/components/schemas/Alternative" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "minItems": 1, "maxItems": 20 }, "job": { "$ref": "#/components/schemas/Job" }, "notification": { "$ref": "#/components/schemas/Notification" } } }, "Subject": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 500, "description": "Email subject. Max length 500 characters." }, "template": { "type": "string", "description": "Template for email subject.", "example": "Subject-Standard-Text ${name}" }, "contentEncoding": { "type": "string", "enum": [ "plain", "base64", "quoted-printable" ], "description": "default=plain", "example": "plain" }, "contentTransferEncoding": { "type": "string", "enum": [ "base64" ], "example": "base64" }, "charset": { "type": "string", "description": "default=UTF-8", "example": "UTF-8" } } }, "Mail": { "type": "object", "required": [ "from" ], "properties": { "from": { "$ref": "#/components/schemas/EmailAddress" }, "mimeFrom": { "$ref": "#/components/schemas/EmailAddress" }, "replyTo": { "$ref": "#/components/schemas/EmailAddress" }, "inReplyTo": { "type": "string", "example": "<1234@example.com>" }, "priority": { "$ref": "#/components/schemas/MailPriority" }, "xHeaders": { "$ref": "#/components/schemas/EmailHeaders" } } }, "EmailAddress": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "maxLength": 254, "example": "john.doe@example.com" } } }, "EmailHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Header names must start with X- max header count=10", "maxProperties": 10, "example": { "X-MY-ADDITIONAL-HEADER": "value1234" } }, "Recipient": { "type": "object", "required": [ "mail" ], "properties": { "mail": { "$ref": "#/components/schemas/RecipientsMail" }, "reference": { "type": "string", "maxLength": 50, "example": "rcpt-632cdc56-6480-406b-8faf-5a7e70876d0c" }, "features": { "$ref": "#/components/schemas/RecipientFeatures" } } }, "RecipientsMail": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" }, "minItems": 1 }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" }, "minItems": 1 }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" }, "minItems": 1 }, "replyTo": { "$ref": "#/components/schemas/EmailAddress" }, "inReplyTo": { "type": "string", "example": "<1234@example.com>" }, "priority": { "$ref": "#/components/schemas/MailPriority" }, "listUnsubscribe": { "type": "string" }, "listHelp": { "type": "string" }, "xHeaders": { "$ref": "#/components/schemas/EmailHeaders" } } }, "MailPriority": { "type": "string", "enum": [ "HIGH", "NORMAL", "LOW" ], "description": "default=NORMAL", "example": "NORMAL" }, "RecipientFeatures": { "type": "object", "properties": { "openTracking": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "linkTracking": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "templating": { "properties": { "personalization": { "type": "object", "additionalProperties": { "type": "string" }, "description": "key-value-map with personalization information", "example": { "name": "John", "surname": "Doe" } } } } } }, "Job": { "type": "object", "properties": { "referenceJob": { "type": "string", "maxLength": 50, "example": "632cdc56-6480-406b-8faf-5a7e70876d0c" }, "costCenter": { "type": "string", "maxLength": 50, "example": "cost-center" }, "campaignId": { "type": "string", "maxLength": 50, "example": "zOsVEmBBV3TYzTPe" }, "features": { "$ref": "#/components/schemas/JobFeatures" } } }, "JobFeatures": { "type": "object", "properties": { "openTracking": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "linkTracking": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "antivirus": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "templating": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "messageSigning": { "type": "object", "properties": { "active": { "type": "boolean" } } }, "secureDocument": { "type": "object", "properties": { "active": { "type": "boolean" }, "filename": { "type": "string", "maxLength": 50 }, "subjectPrefix": { "type": "string", "maxLength": 50 }, "password": { "type": "object", "properties": { "password": { "type": "string", "enum": [ "MEDIUM", "HIGH", "VERY_HIGH" ] } } } } } } }, "Body": { "type": "object", "required": [ "contentType" ], "properties": { "contentType": { "type": "string", "enum": [ "text/plain", "text/html" ], "example": "text/html" }, "charset": { "type": "string", "description": "default=UTF-8", "example": "UTF-8" }, "contentEncoding": { "type": "string", "enum": [ "plain", "quoted-printable", "base64" ], "description": "default=plain", "example": "quoted-printable" }, "contentTransferEncoding": { "type": "string", "enum": [ "base64" ], "example": "base64" }, "content": { "type": "string", "example": "hello world" }, "template": { "type": "string", "description": "Template for email body." } } }, "Alternative": { "type": "object", "properties": { "charset": { "type": "string", "description": "default=UTF-8", "example": "UTF-8" }, "contentEncoding": { "type": "string", "enum": [ "plain", "quoted-printable", "base64" ], "description": "default=plain", "example": "quoted-printable" }, "contentTransferEncoding": { "type": "string", "enum": [ "base64" ], "example": "base64" }, "content": { "type": "string", "example": "hello world." }, "template": { "type": "string", "description": "Template for email alternative." } } }, "Attachment": { "type": "object", "required": [ "name", "contentType", "content" ], "properties": { "name": { "type": "string", "example": "name.pdf" }, "contentType": { "type": "string", "example": "application/pdf" }, "contentId": { "type": "string", "maxLength": 100 }, "content": { "type": "string", "format": "byte", "description": "base64 encoded content", "example": "UmV0YXJ1cyEhCg==" }, "secureDocument": { "type": "boolean" } } }, "Notification": { "type": "object", "properties": { "endPoint": { "$ref": "#/components/schemas/NotificationEndpoint" } } }, "NotificationEndpoint": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "maxLength": 1000, "example": "https://notification-endpoint.example.com/" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "additional HTTP Headers for the notifications", "example": { "X-REQUEST-ID": "3a5d3643-cc2b-41ba-b54f-9bb6a9de6b18" } }, "authentication": { "$ref": "#/components/schemas/NotificationAuthentication" } } }, "NotificationAuthentication": { "type": "object", "required": [ "method", "user", "password" ], "properties": { "method": { "type": "string", "enum": [ "BASIC" ], "example": "BASIC" }, "user": { "type": "string", "maxLength": 100, "example": "notification-user" }, "password": { "type": "string", "maxLength": 100, "example": "dfghoxjuvnzeso374i" } } }, "ResponseAccepted": { "type": "object", "required": [ "meta" ], "properties": { "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "content": { "$ref": "#/components/schemas/ResponseContent" } } }, "ResponseRejected": { "type": "object", "required": [ "meta" ], "properties": { "meta": { "$ref": "#/components/schemas/ResponseMetaBasic" } } }, "ResponseMetaBasic": { "type": "object", "required": [ "jobId", "state" ], "properties": { "jobId": { "type": "string" }, "state": { "$ref": "#/components/schemas/ResponseState" }, "accountId": { "type": "string" } } }, "ResponseMeta": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ResponseMetaBasic" } ], "properties": { "receivedTs": { "type": "string", "format": "date-time" }, "campaignId": { "type": "string" }, "costCenter": { "type": "string" }, "referenceJob": { "type": "string" } } }, "ResponseState": { "type": "object", "properties": { "type": { "type": "string" }, "subType": { "type": "string" }, "phase": { "type": "string" }, "description": { "type": "string" } } }, "ResponseContent": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientResponse" } } } }, "RecipientResponse": { "type": "object", "required": [ "mail" ], "properties": { "mail": { "$ref": "#/components/schemas/RecipientMailResponse" }, "referenceRecipients": { "type": "string" } } }, "RecipientMailResponse": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponse" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponse" } }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponse" } } } }, "EmailAddressResponse": { "type": "object", "required": [ "id" ], "allOf": [ { "$ref": "#/components/schemas/EmailAddress" } ], "properties": { "id": { "type": "string", "example": "22579950-b1cb-4ad8-be2b-715d63a06fcd#999dc92b#a0b50b76" }, "validationResult": { "$ref": "#/components/schemas/ValidationResult" } } }, "ValidationResult": { "type": "object", "properties": { "classifier": { "type": "string" }, "message": { "type": "string" } } } }, "examples": { "EmailJobMinimalRequest": { "summary": "minimal", "value": { "subject": { "content": "minimal subject" }, "recipients": [ { "mail": { "to": [ { "email": "test-01@null.dev.retloc" } ] } } ], "mail": { "from": { "email": "test@bot.com" } } } }, "EmailJobExampleRequest": { "summary": "example", "value": { "mail": { "from": { "email": "john.doe@example.com" } }, "recipients": [ { "mail": { "to": [ { "email": "jane.doe@example.com" } ] } } ], "subject": { "content": "Hello" }, "body": { "contentType": "text/html", "content": "hello world" }, "alternative": { "content": "hello world" }, "attachments": [ { "name": "name.pdf", "contentType": "application/pdf", "content": "aGVsbG8gd29ybGQ=" } ], "job": { "referenceJob": "632cdc56-6480-406b-8faf-5a7e70876d0c", "costCenter": "cost-center", "campaignId": "zOsVEmBBV3TYzTPe" } } }, "EmailJobCompleteRequest": { "summary": "complete", "value": { "mail": { "from": { "email": "john.doe@example.com" }, "mimeFrom": { "email": "john.doe@example.com" }, "replyTo": { "email": "john.doe@example.com" }, "inReplyTo": "<1234@example.com>", "priority": "NORMAL", "xHeaders": { "X-MY-ADDITIONAL-HEADER": "value1234" } }, "recipients": [ { "mail": { "to": [ { "email": "john.doe@example.com" } ], "cc": [ { "email": "john.doe@example.com" } ], "bcc": [ { "email": "john.doe@example.com" } ], "replyTo": { "email": "john.doe@example.com" }, "inReplyTo": "<1234@example.com>", "priority": "NORMAL", "listUnsubscribe": "string", "listHelp": "string", "xHeaders": { "X-MY-ADDITIONAL-HEADER": "value1234" } }, "reference": "rcpt-632cdc56-6480-406b-8faf-5a7e70876d0c", "features": { "openTracking": { "active": true }, "linkTracking": { "active": true }, "templating": { "personalization": { "name": "John", "surname": "Doe" } } } } ], "subject": { "content": "string", "template": "Subject-Standard-Text ${name}", "contentEncoding": "plain", "contentTransferEncoding": "base64", "charset": "UTF-8" }, "body": { "contentType": "text/html", "charset": "UTF-8", "contentEncoding": "quoted-printable", "contentTransferEncoding": "base64", "content": "hello world", "template": "string" }, "alternative": { "charset": "UTF-8", "contentEncoding": "quoted-printable", "contentTransferEncoding": "base64", "content": "hello world.", "template": "string" }, "attachments": [ { "name": "name.pdf", "contentType": "application/pdf", "contentId": "string", "content": "string", "secureDocument": true } ], "job": { "referenceJob": "632cdc56-6480-406b-8faf-5a7e70876d0c", "costCenter": "cost-center", "campaignId": "zOsVEmBBV3TYzTPe", "features": { "openTracking": { "active": true }, "linkTracking": { "active": true }, "antivirus": { "active": true }, "templating": { "active": true }, "messageSigning": { "active": true }, "secureDocument": { "active": true, "filename": "string", "subjectPrefix": "string", "password": { "password": "MEDIUM" } } } }, "notification": { "endPoint": { "url": "https://notification-endpoint.example.com/", "headers": { "X-REQUEST-ID": "3a5d3643-cc2b-41ba-b54f-9bb6a9de6b18" }, "authentication": { "method": "BASIC", "user": "notification-user", "password": "dfghoxjuvnzeso374i" } } } } }, "ResponseAccepted": { "summary": "accepted", "value": { "meta": { "jobId": "22579950-b1cb-4ad8-be2b-715d63a06fcd", "state": { "type": "ACCEPTED", "subType": "FULL", "phase": "PRE_PROCESS" } }, "content": { "recipients": [ { "mail": { "to": [ { "email": "john.doe@example.com", "id": "22579950-b1cb-4ad8-be2b-715d63a06fcd#999dc92b#a0b50b76" } ] } } ] } } }, "ResponseAcceptedPart": { "summary": "partial accepted", "value": { "meta": { "jobId": "22579950-b1cb-4ad8-be2b-715d63a06fcd", "receivedTs": "2023-02-02T08:51:42.097Z", "state": { "type": "ACCEPTED", "subType": "PART", "phase": "PRE_PROCESS" } }, "content": { "recipients": [ { "mail": { "to": [ { "id": "22579950-b1cb-4ad8-be2b-715d63a06fcd#999dc92b#92059835", "email": "jane.doe@example.com" }, { "id": "22579950-b1cb-4ad8-be2b-715d63a06fcd#999dc92b#a0b50b76", "email": "not-an-address", "validationResult": { "classifier": "INVALID_FORMAT" } } ] } } ] } } } } } }