{ "openapi": "3.1.0", "info": { "title": "MailAfrica API", "version": "1.0.0", "description": "Email infrastructure for Africa: inbound addresses + webhooks, outbound transactional email, sending domains (DKIM/SPF/DMARC), AI auto-reply, SMS notifications, sandbox SMTP, and a TZS wallet. Pay-per-message at a flat 5 TZS per message/recipient on any domain; minimum top-up 2,000 TZS.", "contact": { "name": "MailAfrica", "url": "https://mailafrica.online" } }, "servers": [ { "url": "https://api.mailafrica.online" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "OutboundMessage": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "from_address": { "type": "string", "format": "email" }, "to_addresses": { "type": "array", "items": { "type": "string", "format": "email" } }, "cc_addresses": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc_addresses": { "type": "array", "items": { "type": "string", "format": "email" } }, "subject": { "type": "string" }, "html_body": { "type": "string" }, "text_body": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "failed" ] }, "error_code": { "type": "string" }, "provider_message_id": { "type": "string" }, "amount_tzs": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "InboundAddress": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "local_part": { "type": "string" }, "label": { "type": "string" }, "domain_id": { "type": [ "integer", "null" ] }, "retention_days": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "InboundMessage": { "type": "object", "properties": { "id": { "type": "integer" }, "address_id": { "type": "integer" }, "from_addr": { "type": "string" }, "to_addr": { "type": "string" }, "subject": { "type": "string" }, "text_body": { "type": "string" }, "html_body": { "type": "string" }, "headers": { "type": "object" }, "attachments": { "type": "array", "items": { "type": "object" } }, "is_read": { "type": "boolean" }, "received_at": { "type": "string", "format": "date-time" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "address_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "description": "`whsec_...` — shown once at creation" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Topup": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "amount_tzs": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "provider_reference": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "AgentConfig": { "type": "object", "properties": { "address_id": { "type": "integer" }, "user_id": { "type": "integer" }, "mode": { "type": "string", "enum": [ "off", "draft", "auto" ] }, "persona": { "type": "string" }, "enabled": { "type": "boolean" }, "reply_from_domain_id": { "type": [ "integer", "null" ] }, "reply_from_address": { "type": [ "string", "null" ], "format": "email" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "paths": { "/api/auth/register": { "post": { "summary": "Create an account", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "company_name": { "type": "string" }, "email": { "type": "string", "format": "email", "description": "Optional if phone_number is set" }, "phone_number": { "type": "string", "description": "+255… Optional if email is set" }, "password": { "type": "string" } }, "required": [ "name", "password" ] } } } }, "responses": { "200": { "description": "Account created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "status": "400", "description": "`VALIDATION_ERROR` — invalid body" } } } }, "/api/auth/login": { "post": { "summary": "Log in (JWT for dashboard flows)", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Email (contains @) or Tanzanian phone number" }, "password": { "type": "string" } }, "required": [ "identifier", "password" ] } } } }, "responses": { "200": { "description": "Tokens issued", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "refresh_token": { "type": "string" }, "user": { "type": "object" } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/google": { "post": { "summary": "Log in with Google (ID token)", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id_token": { "type": "string" } }, "required": [ "id_token" ] } } } }, "responses": { "200": { "description": "Tokens issued", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/refresh": { "post": { "summary": "Refresh an access token", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ] } } } }, "responses": { "200": { "description": "New tokens", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/me": { "get": { "summary": "Read your profile (JWT required)", "tags": [ "Auth" ], "parameters": [ { "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" }, "description": "JWT bearer token: `Authorization: Bearer `. Issued by register/login." } ], "responses": { "200": { "description": "Current user", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "patch": { "summary": "Update name / company_name (JWT required)", "tags": [ "Auth" ], "parameters": [ { "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" }, "description": "JWT bearer token: `Authorization: Bearer `. Issued by register/login." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "company_name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated user", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/email": { "post": { "summary": "Set a new email and send a verification link", "tags": [ "Auth" ], "parameters": [ { "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" }, "description": "JWT bearer token: `Authorization: Bearer `. Issued by register/login." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Verification email sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/email/resend": { "post": { "summary": "Re-send the verification link to the current email", "tags": [ "Auth" ], "parameters": [ { "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" }, "description": "JWT bearer token: `Authorization: Bearer `. Issued by register/login." } ], "responses": { "200": { "description": "Verification email sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/email/verify": { "post": { "summary": "Confirm email via single-use link token (public)", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Email verified", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/phone": { "post": { "summary": "Set a new phone and send an OTP", "tags": [ "Auth" ], "parameters": [ { "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" }, "description": "JWT bearer token: `Authorization: Bearer `. Issued by register/login." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "description": "+255…" } }, "required": [ "phone_number" ] } } } }, "responses": { "200": { "description": "OTP sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/phone/verify": { "post": { "summary": "Verify a phone with the 6-digit OTP", "tags": [ "Auth" ], "parameters": [ { "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" }, "description": "JWT bearer token: `Authorization: Bearer `. Issued by register/login." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Phone verified", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/auth/phone/resend": { "post": { "summary": "Re-send the OTP to the current phone", "tags": [ "Auth" ], "parameters": [ { "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" }, "description": "JWT bearer token: `Authorization: Bearer `. Issued by register/login." } ], "responses": { "200": { "description": "OTP sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/apikeys/": { "get": { "summary": "List API keys", "tags": [ "API keys" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Key list (no secrets)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Create an API key (plaintext shown once)", "tags": [ "API keys" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "string", "default": "full", "description": "`full`, or comma-separated scopes to restrict" }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional automatic expiry" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "`key` is the plaintext MAIL_... secret — store it immediately", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "key": { "type": "string" } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/apikeys/{id}": { "delete": { "summary": "Revoke an API key", "tags": [ "API keys" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "API key id" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/apikeys/{id}/revoke": { "post": { "summary": "Revoke an API key (POST form)", "tags": [ "API keys" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "API key id" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/inbound/addresses": { "get": { "summary": "List sender IDs (inbound addresses)", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Addresses", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboundAddress" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Create a sender ID (max 100 per account)", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "local_part": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "label": { "type": "string" }, "domain_id": { "type": "integer", "description": "Omit to use @mailafrica.online" } }, "required": [ "local_part" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/InboundAddress" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "409": { "status": "409", "description": "`CONFLICT / LIMIT_REACHED` — taken or cap hit" } } } }, "/api/inbound/addresses/{id}": { "delete": { "summary": "Delete a sender ID", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Address id" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/inbound/domains": { "get": { "summary": "List receiving domains", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Domains with DNS records", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Add a receiving domain (max 100)", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" } }, "required": [ "domain" ] } } } }, "responses": { "201": { "description": "Domain + TXT/MX/A records to publish", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/inbound/domains/{id}/verify": { "post": { "summary": "Verify receiving-domain DNS", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Domain id" } ], "responses": { "200": { "description": "Verified, or code PENDING while DNS propagates", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/inbound/domains/{id}": { "delete": { "summary": "Delete a receiving domain", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Domain id" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/inbound/messages": { "get": { "summary": "List received messages", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "query", "name": "address_id", "schema": { "type": "integer" } }, { "in": "query", "name": "unread", "schema": { "type": "boolean" } }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 } }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated messages", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboundMessage" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/inbound/messages/{id}": { "get": { "summary": "Get one message (full bodies)", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Message id" } ], "responses": { "200": { "description": "Message", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/InboundMessage" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/inbound/messages/{id}/read": { "patch": { "summary": "Mark a message read", "tags": [ "Inbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Message id" } ], "responses": { "200": { "description": "Marked", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/webhook/webhooks": { "get": { "summary": "List webhooks (address_id required)", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "query", "name": "address_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhooks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Create a webhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "description": "Optional `whsec_...` — generated for you if omitted" } }, "required": [ "address_id", "url" ] } } } }, "responses": { "201": { "description": "Created — save the whsec_ secret", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Webhook" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/webhook/webhooks/{id}": { "delete": { "summary": "Delete a webhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Webhook id" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/webhook/webhooks/{id}/deliveries": { "get": { "summary": "Delivery history for a webhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Webhook id" } ], "responses": { "200": { "description": "Deliveries: pending | retrying | delivered | failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/webhook/webhooks/{id}/test": { "post": { "summary": "Send a test event", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Webhook id" } ], "responses": { "200": { "description": "Test delivered", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/webhook/webhooks/trigger/{id}": { "post": { "summary": "Re-dispatch an inbound message to its webhooks", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Inbound message id" } ], "responses": { "200": { "description": "Triggered", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sms/notifications": { "get": { "summary": "List SMS notifications", "tags": [ "SMS notifications" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "query", "name": "address_id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notifications", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Forward an address's mail to SMS", "tags": [ "SMS notifications" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "integer" }, "phone_number": { "type": "string", "description": "+255… or 0… Tanzanian mobile" }, "api_key": { "type": "string", "description": "SendAfrica API key used to send the SMS" } }, "required": [ "address_id", "phone_number", "api_key" ] } } } }, "responses": { "201": { "description": "Created — api_key echoed once", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sms/notifications/{id}/deliveries": { "get": { "summary": "SMS delivery history", "tags": [ "SMS notifications" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Notification id" } ], "responses": { "200": { "description": "sent | failed per attempt", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sms/notifications/{id}/revoke": { "post": { "summary": "Stop forwarding to SMS", "tags": [ "SMS notifications" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Notification id" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/outbound/emails": { "get": { "summary": "List sent email", "tags": [ "Outbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 } }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated history", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundMessage" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Send one email (flat 5 TZS per recipient)", "tags": [ "Outbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" } }, "subject": { "type": "string" }, "html_body": { "type": "string" }, "text_body": { "type": "string" }, "attachments": { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "data_base64": { "type": "string" } }, "required": [ "filename", "data_base64" ] } }, "template_id": { "type": "integer" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "from_domain_id": { "type": "integer" }, "from_address": { "type": "string", "format": "email", "description": "With from_domain_id: a sender on that domain. Without: any local part on @mailafrica.online (e.g. food@mailafrica.online); other domains rejected." } }, "required": [ "to", "subject" ] } } } }, "responses": { "201": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/OutboundMessage" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "402": { "status": "402", "description": "`INSUFFICIENT_BALANCE` — top up and retry" }, "429": { "status": "429", "description": "`RATE_LIMITED` — 2 emails/sec, burst 2" } } } }, "/api/outbound/emails/batch": { "post": { "summary": "Batch send (flat recipient list, chunks of 50)", "tags": [ "Outbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "subject": { "type": "string" }, "html_body": { "type": "string" }, "text_body": { "type": "string" } }, "required": [ "to", "subject" ] } } } }, "responses": { "200": { "description": "Per-recipient results", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "total": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/outbound/emails/{id}": { "get": { "summary": "Get one sent message with per-recipient status", "tags": [ "Outbound" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Message id" } ], "responses": { "200": { "description": "Message detail", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/OutboundMessage" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/outbound/templates": { "get": { "summary": "List templates", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Create a template ({{key}} placeholders)", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subject": { "type": "string" }, "html_body": { "type": "string" }, "text_body": { "type": "string" } }, "required": [ "name", "subject" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/outbound/templates/{id}": { "patch": { "summary": "Replace a template (full replace)", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Template id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "delete": { "summary": "Delete a template", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Template id" } ], "responses": { "200": { "description": "Returns deleted_template_id", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/domains/": { "get": { "summary": "List sending domains", "tags": [ "Sending domains" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Domains + DNS records", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Add a sending domain (max 5)", "tags": [ "Sending domains" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "from_local_part": { "type": "string", "default": "noreply" } }, "required": [ "domain" ] } } } }, "responses": { "201": { "description": "Domain + DKIM/SPF/DMARC TXT records", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/domains/{id}/verify": { "post": { "summary": "Verify sending-domain DNS", "tags": [ "Sending domains" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Domain id" } ], "responses": { "200": { "description": "Domain with status pending | verified | suspended; all three DNS records must resolve", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/domains/{id}": { "delete": { "summary": "Delete a sending domain", "tags": [ "Sending domains" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Domain id" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/domains/senders": { "get": { "summary": "List from-addresses across domains", "tags": [ "Sending domains" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Sender addresses", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/domains/{id}/senders": { "post": { "summary": "Add a from-address (100 per account)", "tags": [ "Sending domains" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Domain id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/domains/senders/{id}": { "delete": { "summary": "Delete a from-address", "tags": [ "Sending domains" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Sender address id" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/billing/balance": { "get": { "summary": "Read wallet balance (TZS)", "tags": [ "Billing" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Current balance", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "balance_tzs": { "type": "integer" } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/billing/topup": { "post": { "summary": "Start a hosted top-up (min 2,000 TZS, link expires in 1h)", "tags": [ "Billing" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_tzs": { "type": "integer", "minimum": 2000 } }, "required": [ "amount_tzs" ] } } } }, "responses": { "201": { "description": "Includes checkout_url / payment_link_url", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Topup" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/billing/topup/phone": { "post": { "summary": "USSD mobile-money push to your verified phone", "tags": [ "Billing" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_tzs": { "type": "integer", "minimum": 2000 } }, "required": [ "amount_tzs" ] } } } }, "responses": { "201": { "description": "Push sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Topup" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "status": "400", "description": "`VALIDATION_ERROR` — no verified phone" } } } }, "/api/compliance/profile": { "get": { "summary": "Read PDPC compliance profile", "tags": [ "Compliance" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Profile (created on first read)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "patch": { "summary": "Update compliance profile / retention", "tags": [ "Compliance" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pdpc_registered": { "type": "boolean" }, "pdpc_certificate_number": { "type": "string" }, "pdpc_registered_at": { "type": "string", "format": "date" }, "default_retention_days": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/compliance/audit-export": { "get": { "summary": "Audit summary export", "tags": [ "Compliance" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Own numbers only", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sandbox/credentials": { "get": { "summary": "List sandbox API credentials", "tags": [ "Sandbox" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Credentials", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "summary": "Create sandbox credentials", "tags": [ "Sandbox" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scopes": { "type": "string", "default": "full", "description": "`full` (default) or comma-separated scopes to restrict" } } } } } }, "responses": { "201": { "description": "Secret shown once", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sandbox/credentials/{id}/revoke": { "post": { "summary": "Revoke sandbox credentials", "tags": [ "Sandbox" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Credentials id" } ], "responses": { "200": { "description": "Revoked — SMTP auth stops immediately", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sandbox/credentials/smtp": { "get": { "summary": "Sandbox SMTP settings", "tags": [ "Sandbox" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Password only when fresh", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sandbox/credentials/smtp/regenerate": { "post": { "summary": "Regenerate sandbox SMTP password", "tags": [ "Sandbox" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "New password shown once", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sandbox/messages": { "get": { "summary": "List captured sandbox messages (2,000/month cap)", "tags": [ "Sandbox" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 } }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Captured messages", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "delete": { "summary": "Clear all captured sandbox messages", "tags": [ "Sandbox" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Cleared", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/sandbox/messages/{id}": { "get": { "summary": "Get one captured message", "tags": [ "Sandbox" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Message id" } ], "responses": { "200": { "description": "Full message", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/agent/configs": { "get": { "summary": "List AI auto-reply configs", "tags": [ "AI agent" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." } ], "responses": { "200": { "description": "Configs", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConfig" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/agent/configs/{id}": { "get": { "summary": "Get one config (id = address id)", "tags": [ "AI agent" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Address id" } ], "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/AgentConfig" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "put": { "summary": "Update mode/persona/reply-from", "tags": [ "AI agent" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Address id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "draft", "auto" ] }, "persona": { "type": "string" }, "enabled": { "type": "boolean" }, "reply_from_domain_id": { "type": "integer" }, "reply_from_address": { "type": "string", "format": "email" } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/AgentConfig" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/agent/configs/{id}/draft": { "post": { "summary": "Preview an AI draft reply (never sends)", "tags": [ "AI agent" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string", "pattern": "^MAIL_[0-9a-f]{64}$" }, "description": "MailAfrica API key. `Authorization: Bearer MAIL_...` also accepted." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Address id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string" }, "text_body": { "type": "string" } } } } } }, "responses": { "200": { "description": "Draft text", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "timestamp" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "draft": { "type": "string" } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "503": { "status": "503", "description": "`NOT_CONFIGURED` — LLM gateway not configured server-side" } } } } } }