{
  "basePath": "/api/v1",
  "definitions": {
    "RelayEmailAttachment": {
      "properties": {
        "checksum": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "emailMessageId": {
          "type": "string"
        },
        "fileSize": {
          "type": "integer"
        },
        "filename": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "mimeType": {
          "type": "string"
        },
        "originalFilename": {
          "type": "string"
        },
        "storageKey": {
          "type": "string"
        },
        "storageProvider": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "RelayEmailEvent": {
      "properties": {
        "createdAt": {
          "type": "string"
        },
        "customerId": {
          "type": "integer"
        },
        "emailMessageId": {
          "description": "EmailMessageID is null for compliance events (suppression.added/removed)\nthat are not tied to a specific outbound message.",
          "type": "string"
        },
        "eventPayload": {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        "eventType": {
          "type": "string"
        },
        "eventVersion": {
          "type": "integer"
        },
        "id": {
          "type": "string"
        },
        "ownerType": {
          "type": "string"
        },
        "recipient": {
          "description": "Recipient holds the email address involved in the event (bounce, engagement,\nsuppression). Populated where known; empty for internal state transitions.",
          "type": "string"
        },
        "source": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "RelayEmailMessage": {
      "properties": {
        "applicationId": {
          "type": "string"
        },
        "bccEmails": {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        "bounceAddress": {
          "type": "string"
        },
        "bouncedAt": {
          "type": "string"
        },
        "ccEmails": {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        "createdAt": {
          "type": "string"
        },
        "customerId": {
          "type": "integer"
        },
        "failedAt": {
          "type": "string"
        },
        "fromEmail": {
          "type": "string"
        },
        "fromName": {
          "type": "string"
        },
        "htmlBody": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "idempotencyKey": {
          "description": "IdempotencyKey is unique per-tenant, not globally: see idx_relay_email_messages_customer_idempotency.",
          "type": "string"
        },
        "lastError": {
          "type": "string"
        },
        "maxRetries": {
          "type": "integer"
        },
        "messageIdHeader": {
          "type": "string"
        },
        "metadata": {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        "nextRetryAt": {
          "type": "string"
        },
        "ownerType": {
          "type": "string"
        },
        "processingAt": {
          "type": "string"
        },
        "providerMessageId": {
          "type": "string"
        },
        "queuedAt": {
          "type": "string"
        },
        "replyToEmail": {
          "type": "string"
        },
        "requestId": {
          "type": "string"
        },
        "retryCount": {
          "type": "integer"
        },
        "sentAt": {
          "type": "string"
        },
        "smtpConfigId": {
          "type": "string"
        },
        "smtpResponse": {
          "type": "string"
        },
        "smtpResponseCode": {
          "type": "integer"
        },
        "sourceService": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "statusReason": {
          "type": "string"
        },
        "subject": {
          "type": "string"
        },
        "submissionChannel": {
          "type": "string"
        },
        "tags": {
          "description": "Tags is a first-class JSON array of short labels (distinct from the\nfree-form Metadata bag) used for filtering and grouping in the portal,\nconsole, and public API (spec §6.10/§11.9).",
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        "textBody": {
          "type": "string"
        },
        "toEmail": {
          "type": "string"
        },
        "trackClicks": {
          "type": "boolean"
        },
        "trackOpens": {
          "type": "boolean"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "attachmentInput": {
      "properties": {
        "content": {
          "description": "Content is the file's raw bytes, base64-encoded.",
          "type": "string"
        },
        "contentType": {
          "description": "ContentType is the MIME type, e.g. \"application/pdf\". Must be one of\nthe platform's allowed attachment types.",
          "type": "string"
        },
        "filename": {
          "description": "Filename shown to the recipient, e.g. \"invoice.pdf\".",
          "type": "string"
        }
      },
      "type": "object"
    },
    "batchSendItemResult": {
      "properties": {
        "canonicalStatus": {
          "type": "string"
        },
        "code": {
          "type": "string"
        },
        "error": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "index": {
          "type": "integer"
        },
        "status": {
          "type": "string"
        },
        "tenantId": {
          "type": "integer"
        }
      },
      "type": "object"
    },
    "batchSendRequest": {
      "properties": {
        "messages": {
          "items": {
            "$ref": "#/definitions/sendEmailRequest"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "errorResponse": {
      "properties": {
        "error": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "relayMessageDetailResponse": {
      "properties": {
        "attachments": {
          "items": {
            "$ref": "#/definitions/RelayEmailAttachment"
          },
          "type": "array"
        },
        "canonicalStatus": {
          "type": "string"
        },
        "events": {
          "items": {
            "$ref": "#/definitions/RelayEmailEvent"
          },
          "type": "array"
        },
        "message": {
          "$ref": "#/definitions/RelayEmailMessage"
        }
      },
      "type": "object"
    },
    "relayPingResponse": {
      "properties": {
        "service": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "sendEmailRequest": {
      "properties": {
        "applicationId": {
          "description": "ApplicationID optionally tags this message with one of your\nregistered applications (Applications tab in the dashboard), for\nper-application logs/usage and enforcing that application's own\nsend limits (a tier between your package limit and the SMTP config's\nown limit). Optional. If smtpConfigId resolves to a config that is\nitself scoped to an application, applicationId is inherited from the\nconfig automatically when omitted; supplying a different\napplicationId than the config's own application is rejected with 400.",
          "type": "string"
        },
        "attachments": {
          "description": "Attachments are base64-encoded in this JSON body. Requires the\nattachments feature on your plan; size is capped per your plan's\nmax-attachment-size setting.",
          "items": {
            "$ref": "#/definitions/attachmentInput"
          },
          "type": "array"
        },
        "bcc": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "cc": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "fromEmail": {
          "description": "Sender email address. Subject to sender-domain authorization if your\naccount has that enforcement enabled.",
          "type": "string"
        },
        "fromName": {
          "description": "Sender display name, e.g. \"Acme Billing\".",
          "type": "string"
        },
        "html": {
          "description": "HTML body. At least one of html or text is required.",
          "type": "string"
        },
        "idempotencyKey": {
          "description": "IdempotencyKey, when supplied, is unique per API key. Replaying the\nsame key returns the original send's result instead of creating a\nduplicate message.",
          "type": "string"
        },
        "metadata": {
          "additionalProperties": {},
          "description": "Metadata is an arbitrary JSON object stored with the message and\nechoed back in message-detail responses; not indexed or filterable.",
          "type": "object"
        },
        "replyTo": {
          "type": "string"
        },
        "smtpConfigId": {
          "description": "SMTPConfigID selects which of your SMTP configs to send through.\nOptional — omit to use whichever config is marked as default; if none\nis marked default, the send is rejected with \"no default SMTP config\nfound\". If the chosen config is itself scoped to an application, this\nmessage's applicationId is validated/derived from it (see\napplicationId below).",
          "type": "string"
        },
        "sourceService": {
          "description": "SourceService is a free-form label for the system that submitted this\nsend (e.g. \"billing-worker\"), stored for operational filtering only.",
          "type": "string"
        },
        "subject": {
          "description": "Email subject line.",
          "type": "string"
        },
        "tags": {
          "description": "Tags are short labels (e.g. \"welcome-series\") usable for filtering\nmessages in the dashboard and via the emails-list API.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "text": {
          "description": "Plain-text body. At least one of html or text is required.",
          "type": "string"
        },
        "to": {
          "description": "Recipient email address.",
          "type": "string"
        },
        "trackClicks": {
          "description": "TrackClicks rewrites links in the HTML body for click tracking.\nRequires the engagement-tracking feature on your plan, or the send is\nrejected.",
          "type": "boolean"
        },
        "trackOpens": {
          "description": "TrackOpens embeds a tracking pixel to record opens. Requires the\nengagement-tracking feature on your plan, or the send is rejected.",
          "type": "boolean"
        }
      },
      "required": [
        "fromEmail",
        "subject",
        "to"
      ],
      "type": "object"
    },
    "sendEmailResponse": {
      "properties": {
        "canonicalStatus": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "tenantId": {
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "host": "",
  "info": {
    "contact": {
      "email": "info@ridgital.com",
      "name": "Ridgital",
      "url": "https://ridgital.com"
    },
    "description": "---\n\nRidgital Relay is a transactional email delivery service that enables your applications to send emails, monitor delivery status, and retrieve the complete lifecycle of every submitted message.\n\n---\n\n# Getting Started\n\nBefore using the Relay API:\n\n1. Create a Ridgital Relay account.\n2. Subscribe to one of the available Relay plans.\n3. Configure your organization.\n4. Create an API Key from the Customer Portal.\n5. Use the generated API Key to authenticate your requests.\n\nYour API Key belongs to your organization and is required for every Relay API request.\n\n# Authentication\n\n```http\nAuthorization: Bearer rdg_\u003cyour_api_key\n```\n\nRequests without a valid API Key return **401 Unauthorized**.\n\n# Base URL\n\n```text\nhttps://ridgital.com/api/v1\n```\n\n# Available Endpoints\n\n| Method | Endpoint | Description |\n|---|---|---|\n| POST | `/relay/send` | Queue a transactional email for delivery. |\n| POST | `/relay/send/batch` | Queue up to 100 transactional emails. |\n| GET | `/relay/messages/{message_id}` | Retrieve delivery status and lifecycle. |\n| GET | `/relay/emails` | List submitted messages. |\n| GET | `/relay/ping` | Validate API availability and API Key. |\n\n# Asynchronous Processing\n\nA successful response means the message has been **accepted and queued**, not necessarily delivered. Delivery, retries, bounce processing, tracking, and Webhook notifications occur asynchronously.\n\n# Delivery Status\n\n`canonicalStatus` values:\n\n`submitted`, `accepted`, `delivered`, `deferred`, `hard_bounced`, `soft_bounced`, `suppressed`, `failed`\n\n`delivered` means the message has been accepted by your configured outbound SMTP server. Inbox placement is not guaranteed. Later DSN/Bounce reports may change the status to `hard_bounced` or `soft_bounced`.\n\n# One-Click Unsubscribe\n\nWhen `trackOpens` or `trackClicks` is enabled, Relay automatically adds the RFC 8058 unsubscribe headers. One-click unsubscribe requests automatically create a `Suppression` record with reason `unsubscribe`.\n\n# ISP Feedback Loop (FBL)\n\nRegister ISP feedback loops using **your own** sending domain/IP. Configure the feedback mailbox to be the same as your Delivery SMTP bounce mailbox. Relay automatically processes abuse reports and creates `Suppression` records with reason `complaint`.\n\n# Security\n\n- Never expose your API Key.\n- Store API Keys securely.\n- Rotate compromised API Keys immediately.\n- Always use HTTPS.\n\n# Support\n\n**info@ridgital.com**\n",
    "title": "Ridgital Relay API",
    "version": "1.0",
    "x-logo": {
      "altText": "Ridgital",
      "href": "/",
      "url": "/logo.png"
    }
  },
  "paths": {
    "/relay/messages/{id}": {
      "get": {
        "description": "Returns the message record, lifecycle events (queued, processing, sent, bounced, failed), and attachment metadata for a message created by POST /relay/send.\nUse this endpoint to build delivery dashboards or confirm whether an email reached the recipient's mail server.",
        "parameters": [
          {
            "description": "Message UUID returned by POST /relay/send",
            "in": "path",
            "name": "id",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/relayMessageDetailResponse"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/errorResponse"
            }
          }
        },
        "security": [
          {
            "RelayAPIKey": []
          }
        ],
        "summary": "Get email delivery status",
        "tags": [
          "Messages"
        ]
      }
    },
    "/relay/ping": {
      "get": {
        "description": "Verifies the Relay API is reachable and your API key is valid. Call this after configuring your API key to confirm connectivity before sending production traffic.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/relayPingResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/errorResponse"
            }
          }
        },
        "security": [
          {
            "RelayAPIKey": []
          }
        ],
        "summary": "Health check",
        "tags": [
          "Connectivity"
        ]
      }
    },
    "/relay/send": {
      "post": {
        "consumes": [
          "application/json"
        ],
        "description": "Queues an email for delivery via your configured SMTP server (set up in the Ridgital Console under Relay → SMTP Configs).\nProvide at least one of `html` or `text`. Attachments are base64-encoded in the JSON body; binaries are stored securely and delivered by the relay worker.\nUse `idempotencyKey` to safely retry without duplicate sends. Poll `GET /relay/messages/{id}` for status (`queued`, `sent_to_smtp`, `permanent_failed`, etc.).\nAuthenticate with your API key: `Authorization: Bearer rdg_\u003ckey\u003e`.",
        "parameters": [
          {
            "description": "Email payload",
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/sendEmailRequest"
            }
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/sendEmailResponse"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/errorResponse"
            }
          }
        },
        "security": [
          {
            "RelayAPIKey": []
          }
        ],
        "summary": "Send a transactional email",
        "tags": [
          "Sending"
        ]
      }
    },
    "/relay/send/batch": {
      "post": {
        "consumes": [
          "application/json"
        ],
        "description": "Queues multiple emails for delivery in a single call. Each message is validated and quota-checked independently — one failing item does not block the others. Returns per-item results in request order.\nAuthenticate with your API key: `Authorization: Bearer rdg_\u003ckey\u003e`.",
        "parameters": [
          {
            "description": "Batch of email payloads (max 100)",
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/batchSendRequest"
            }
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "properties": {
                "results": {
                  "items": {
                    "$ref": "#/definitions/batchSendItemResult"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/errorResponse"
            }
          }
        },
        "security": [
          {
            "RelayAPIKey": []
          }
        ],
        "summary": "Send up to 100 transactional emails in one request",
        "tags": [
          "Sending"
        ]
      }
    }
  },
  "schemes": [],
  "securityDefinitions": {
    "ArmidAPIKey": {
      "description": "Ridgital API key for ARMID Explorer. Format: \"Bearer rdg_\u003ckey\u003e\". Create keys in the Ridgital dashboard under **Account → API Keys**; a key works while the account's ARMID Explorer access is active.",
      "in": "header",
      "name": "Authorization",
      "type": "apiKey"
    },
    "CSRFToken": {
      "in": "header",
      "name": "X-CSRF-Token",
      "type": "apiKey"
    },
    "CookieAuth": {
      "in": "cookie",
      "name": "ridgital_session",
      "type": "apiKey"
    },
    "RelayAPIKey": {
      "description": "Ridgital Relay API key. Format: \"Bearer rdg_\u003ckey\u003e\". Create keys in the Ridgital Console under **API Keys** (customer login required).",
      "in": "header",
      "name": "Authorization",
      "type": "apiKey"
    }
  },
  "swagger": "2.0",
  "tags": [
    {
      "description": "Queue one email or a batch for delivery.",
      "name": "Sending"
    },
    {
      "description": "A submitted message's delivery status and lifecycle.",
      "name": "Messages"
    },
    {
      "description": "Check that your API key works.",
      "name": "Connectivity"
    }
  ]
}