diff --git a/README.md b/README.md
index 40f5e4e..d3d84c1 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,7 @@
-# mailsaviour-spec
\ No newline at end of file
+# mailsaviour-spec
+
+This repo contains the specification for our (or hopefully all) mail save systems developed in this course: https://www.dcl.hpi.uni-potsdam.de/teaching/SRE/
+
+The spec itself is located at `spec.yml` and is written in the OpenAPI 3.0 format. You can create these files with every text editor and the IDE-like web editor at https://editor.swagger.io
+
+Feel free to create your own fork and/or submit Pull Request so we are using all the same specs. If you have any questions don't hesitate to contact us.
diff --git a/spec.yml b/spec.yml
new file mode 100644
index 0000000..168c65d
--- /dev/null
+++ b/spec.yml
@@ -0,0 +1,204 @@
+openapi: "3.0.0"
+info:
+  description: "This is the API definition for the Datenkrake frontend."
+  version: "1.0.0"
+  title: "Datenkrake Backend"
+  contact:
+    email: "leonard@marschke.me"
+    url: "https://bauth.marschke.me/about"
+servers:
+  - url: "https://someserver/v1"
+
+paths:
+  /health:
+    get:
+      summary: Gets service health
+      responses:
+        200:
+          description: Service operational
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+        503:
+          description: Service not operational
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+        default:
+          $ref: '#/components/responses/Error'
+
+  /mailstore:
+    get:
+      summary: Get saved mails
+      description: To get filtered results you can specify query parameters, which get concatenated by AND
+      parameters:
+        - name: id
+          in: query
+          description: Filter for id
+          schema:
+            type: string
+            description: Id generated by POST
+        - name: received_before
+          in: query
+          description: Filter for received date
+          schema:
+            type: string
+            format: datetime
+            description: Time in RFC 3339 format
+            example: "2018-06-10T10:11:46.8328983+02:00"
+        - name: received_after
+          in: query
+          description: Filter for received date
+          schema:
+            type: string
+            format: datetime
+            description: Time in RFC 3339 format
+            example: "2018-06-10T10:11:46.8328983+02:00"
+        - name: mail_from
+          in: query
+          description: Filter for mail sender
+          schema:
+            type: string
+            format: mail
+            description: Mail sender address
+        - name: rcpt_to
+          in: query
+          description: Filter for mail receipient
+          schema:
+            type: string
+            format: mail
+            description: Mail rcpt address
+      responses:
+        200:
+          description: Mail content
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  mail_list:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          $ref: '#/components/schemas/MailId'
+                        content:
+                          $ref: '#/components/schemas/Mail'
+
+        400:
+          $ref: '#/components/responses/InvalidArgument'
+        404:
+          $ref: '#/components/responses/NotFound'
+        422:
+          $ref: '#/components/responses/UnprocessableEntity'
+        default:
+          $ref: '#/components/responses/Error'
+    post:
+      summary: Save a new mail
+      requestBody:
+        description: "Mail content"
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Mail'
+      responses:
+        200:
+          description: Mail successfully saved
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    $ref: '#/components/schemas/MailId'
+        400:
+          $ref: '#/components/responses/InvalidArgument'
+        422:
+          $ref: '#/components/responses/UnprocessableEntity'
+        default:
+          $ref: '#/components/responses/Error'
+
+
+
+components:
+  schemas:
+    HealthResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          description: Current status of the service
+        message:
+          type: string
+          description: Explaining the current status
+    Error:
+      type: object
+      properties:
+        message:
+          type: string
+          description: the error message
+    Mail:
+      type: object
+      properties:
+        received:
+          type: string
+          format: datetime
+          description: Time in RFC 3339 format
+          example: "2018-06-10T10:11:46.8328983+02:00"
+        received_from:
+          type: string
+          description: Server mail received from
+          example: mail.marschke.me
+        received_by:
+          type: string
+          description: Server mail received by
+          example: localhost
+        mail_from:
+          type: string
+          format: mail
+          description: Origin mail address
+          example: leonard@marschke.me
+        rcpt_to:
+          type: array
+          items:
+            type: string
+            format: mail
+            description: Rcpt mail address
+            example: leonard@localhost
+        data:
+          type: string
+          description: Mail content encoded in ASCII chars
+          example: "SRE ist das geilste Seminar ewa!!!"
+    MailId:
+      type: string
+      description: Mail id
+
+  responses:
+    Error:
+      description: Unknown Error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    InvalidArgument:
+      description: Invalid argument passed, see message field for more information.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    NotFound:
+      description: Not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    UnprocessableEntity:
+      description: Request was unable to be completed, due to semantic errors
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'