API Responses

De MMMS API biedt endpoints voor email verzending en API key management. Alle responses volgen een consistent formaat met gestandaardiseerde error handling.

Response Format

Success Response

Alle succesvolle responses volgen dit formaat:

{
  "status": 200,
  "message": "Operation completed successfully",
  "data": {
    // Response data hier
  }
}

Error Response

Alle error responses volgen dit formaat:

{
  "status": 400,
  "message": "Error description",
  "error_type": "validation_error",
  "details": "Additional error details"
}

Health Check

GET /v1/health

Beschrijving: Health check endpoint voor service status

Toegang: Publiek

Headers: Geen vereist

200 OK

Success Response (200):

"OK"

Content-Type: application/json

Mail

POST /v1/mail

Beschrijving: Verstuur email via AWS SES

Toegang: API Key vereist

Headers:

x-api-key: API key voor authenticatie
origin: Origin domain voor validatie
Content-Type: application/json

Request Body:

{
  "recipients": [
    {
      "name": "John Doe",
      "mail": "john@example.com",
      "company": "Acme Corp",
      "emailRecipientId": "recipient-123"
    }
  ],
  "sender_name": "Support Team",
  "sender_email": "support@example.com",
  "sender_organisation_name": "Acme Corp",
  "subject": "Test Email",
  "html_template": "<html><body><h1>Hello {{name}}</h1></body></html>",
  "client_env_id": "env-123",
  "email_id": "msg-123",
  "emailRecipientId": "recipient-123",
  "projectId": "project-456",
  "closureId": "closure-789"
}

200 Email sent successfully

Success Response (200):

{
  "status": 200,
  "message": "Email sent successfully",
  "data": {
    "message_id": "0000014a-f4d4-4c4b-8b7a-123456789012-000000",
    "ses_response": {
      "MessageId": "0000014a-f4d4-4c4b-8b7a-123456789012-000000"
    },
    "status": {
      "email_id": "msg-123",
      "email_recipient_id": "recipient-123",
      "recipient": "john@example.com",
      "status": "sent",
      "message_id": "0000014a-f4d4-4c4b-8b7a-123456789012-000000",
      "status_detail": null,
      "last_error": null,
      "queued_at": null,
      "sent_at": "2025-01-27T10:30:00Z"
    }
  }
}

Error Responses:

401 Unauthorized - Missing API key or origin

{
  "status": 401,
  "message": "Unauthorized - Missing API key or origin"
}

401 Unauthorized - Invalid API key or origin

{
  "status": 401,
  "message": "Unauthorized - Invalid API key or origin"
}

422 Validation failed

{
  "error": "Validation failed",
  "message": "Request validation failed",
  "details": [
    {
      "type": "missing",
      "loc": ["recipients"],
      "msg": "Field required",
      "input": null
    }
  ],
  "request_id": "abc123def456"
}

400 Business logic error

{
  "error": "Business logic error",
  "message": "Request validation failed: recipients field is required",
  "request_id": "abc123def456"
}

500 Internal server error

{
  "error": "Internal server error",
  "request_id": "abc123def456"
}

API Key Management

POST /v1/api-key

Beschrijving: Maak nieuwe API key

Toegang: Publiek

Headers:

Content-Type: application/json

Request Body:

{
  "name": "My API Key",
  "origin_names": ["example.com", "app.example.com"],
  "expires_at": "2026-01-27T10:30:00Z"
}

200 API key created successfully

Success Response (200):

{
  "status": 200,
  "message": "API key created successfully",
  "data": {
    "key_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "My API Key",
    "api_key": "ak_1234567890abcdef",
    "is_active": true,
    "created_at": "2025-01-27T10:30:00Z",
    "origins": [
      {
        "name": "example.com",
        "created_at": "2025-01-27T10:30:00Z"
      },
      {
        "name": "app.example.com",
        "created_at": "2025-01-27T10:30:00Z"
      }
    ],
    "expires_at": "2026-01-27T10:30:00Z"
  }
}

Error Responses:

422 Validation failed

{
  "error": "Validation failed",
  "message": "Request validation failed",
  "details": [
    {
      "type": "missing",
      "loc": ["name"],
      "msg": "Field required",
      "input": null
    }
  ],
  "request_id": "abc123def456"
}

500 Internal server error

{
  "error": "Internal server error",
  "request_id": "abc123def456"
}

DELETE /v1/api-key/{api_key}

Beschrijving: Verwijder API key

Toegang: Publiek

Headers: Geen vereist

Path Parameters:

api_key (string): De API key om te verwijderen

200 API key deleted successfully

Success Response (200):

{
  "status": 200,
  "message": "API key deleted successfully",
  "data": {
    "deleted": true,
    "api_key": "ak_1234567890abcdef"
  }
}

Error Responses:

404 API key not found

{
  "status": 404,
  "message": "API key not found",
  "error_type": "not_found",
  "details": "The specified API key does not exist"
}

500 Internal server error

{
  "error": "Internal server error",
  "request_id": "abc123def456"
}

POST /v1/api-key/{api_key}/origins

Beschrijving: Voeg origins toe aan API key

Toegang: Publiek

Headers:

Content-Type: application/json

Path Parameters:

api_key (string): De API key om origins aan toe te voegen

Request Body:

{
  "origin_names": ["new.example.com", "api.example.com"]
}

200 Origins added to API key successfully

Success Response (200):

{
  "status": 200,
  "message": "Origins added to API key successfully",
  "data": {
    "api_key": "ak_1234567890abcdef",
    "added_origins": [
      {
        "name": "new.example.com",
        "created_at": "2025-01-27T10:30:00Z"
      },
      {
        "name": "api.example.com",
        "created_at": "2025-01-27T10:30:00Z"
      }
    ]
  }
}

Error Responses:

404 API key not found

{
  "status": 404,
  "message": "API key not found",
  "error_type": "not_found",
  "details": "The specified API key does not exist"
}

422 Validation failed

{
  "error": "Validation failed",
  "message": "Request validation failed",
  "details": [
    {
      "type": "missing",
      "loc": ["origin_names"],
      "msg": "Field required",
      "input": null
    }
  ],
  "request_id": "abc123def456"
}

500 Internal server error

{
  "error": "Internal server error",
  "request_id": "abc123def456"
}

SQS Consumer

SQS Event Processing

Queue: mmms-email-processing-queue

Batch Size: 10 messages

Beschrijving: Verwerkt bulk email berichten vanuit SQS queue

Message Format:

{
  "email_id": "msg-123",
  "email_recipient_id": "recipient-123",
  "client_env_id": "env-123",
  "sender_email": "support@example.com",
  "sender_name": "Support Team",
  "sender_organisation_name": "Acme Corp",
  "subject": "Test Email",
  "html_template": "<html><body><h1>Hello {{name}}</h1></body></html>",
  "recipient_name": "John Doe",
  "recipient_email": "john@example.com",
  "recipient_company": "Acme Corp",
  "queued_at": "2025-01-27T10:30:00Z"
}

Processing Result:

{
  "success": true,
  "email_id": "msg-123",
  "email_recipient_id": "recipient-123",
  "recipient": "john@example.com",
  "status": "sent",
  "result": {
    "email_id": "msg-123",
    "email_recipient_id": "recipient-123",
    "recipient": "john@example.com",
    "status": "sent",
    "message_id": "0000014a-f4d4-4c4b-8b7a-123456789012-000000",
    "status_detail": null,
    "last_error": null,
    "queued_at": "2025-01-27T10:30:00Z",
    "sent_at": "2025-01-27T10:30:05Z"
  }
}

Error Types

Validation Error (422)

Trigger: Pydantic model validatie fouten

Response Format:

{
  "error": "Validation failed",
  "message": "Request validation failed",
  "details": [
    {
      "type": "missing",
      "loc": ["field_name"],
      "msg": "Field required",
      "input": null
    }
  ],
  "request_id": "abc123def456"
}

Business Logic Error (400)

Trigger: Business logic fouten

Response Format:

{
  "error": "Business logic error",
  "message": "Error description",
  "request_id": "abc123def456"
}

Authentication Error (401)

Trigger: API key of origin validatie fouten

Response Format:

{
  "status": 401,
  "message": "Unauthorized - Error description"
}

Not Found Error (404)

Trigger: Resource niet gevonden

Response Format:

{
  "status": 404,
  "message": "Resource not found",
  "error_type": "not_found",
  "details": "Additional error details"
}

Internal Server Error (500)

Trigger: Onverwachte fouten

Response Format:

{
  "error": "Internal server error",
  "request_id": "abc123def456"
}

Rate Limiting

Momenteel geen rate limiting geïmplementeerd. Rate limiting kan worden toegevoegd via:

API Gateway throttling
AWS WAF rate limiting
Custom middleware implementatie

CORS

CORS is geconfigureerd via Chalice voor de volgende origins:

Local Development: http://localhost:4321
Production: Configureer in .chalice/config.json

Request/Response Headers

Vereiste Headers

Content-Type: application/json (voor POST requests)
x-api-key: API key voor authenticatie (voor beveiligde endpoints)
origin: Origin domain voor validatie (voor beveiligde endpoints)

Response Headers

Content-Type: application/json
Access-Control-Allow-Origin: Toegestane origin
Access-Control-Allow-Methods: Toegestane HTTP methods
Access-Control-Allow-Headers: Toegestane headers