Providers API

Connect, manage, and validate email provider accounts. Optail supports SendGrid, Postmark, Mailgun, and Amazon SES.

GET /v1/providers

List all provider accounts for the organization. Credentials are never returned.

Response

{
  "data": [
    {
      "id": "pa-uuid",
      "organizationId": "org-uuid",
      "providerType": "SENDGRID",
      "displayName": "SendGrid Production",
      "isActive": true,
      "createdAt": "2025-01-10T08:00:00Z",
      "updatedAt": "2025-01-10T08:00:00Z"
    }
  ]
}

POST /v1/providers

Connect a new provider account. Credentials are validated against the provider's API before being encrypted and stored.

Request Body

Field	Type	Required	Description
providerType	string	Yes	One of: SENDGRID, POSTMARK, MAILGUN, SES.
displayName	string	Yes	A human-readable name for this account (max 255 chars).
credentials	object	Yes	Provider-specific credentials (see below).

Credential Fields by Provider

Provider	Required Fields
SENDGRID	apiKey
POSTMARK	serverToken
MAILGUN	apiKey, domain
SES	accessKeyId, secretAccessKey, region

Example

curl -X POST https://api.optail.io/v1/providers \
  -H "Authorization: Bearer ms_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "SENDGRID",
    "displayName": "SendGrid Production",
    "credentials": {
      "apiKey": "SG.xxxxxxxxxxxxxxxxxxxxx"
    }
  }'

Response

Status: 201 Created

{
  "data": {
    "id": "pa-uuid",
    "organizationId": "org-uuid",
    "providerType": "SENDGRID",
    "displayName": "SendGrid Production",
    "isActive": true,
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-01-10T08:00:00Z"
  }
}

If credentials are invalid, the API returns 422:

{
  "error": {
    "code": "PROVIDER_INVALID_CREDENTIALS",
    "message": "Email provider error (SENDGRID)"
  }
}

GET /v1/providers/:id

Get a single provider account. Credentials are never exposed.

PATCH /v1/providers/:id

Update a provider's display name or active status.

Request Body

Field	Type	Required	Description
displayName	string	No	New display name.
isActive	boolean	No	Enable or disable the provider.

DELETE /v1/providers/:id

Remove a provider account. Any routing rules pointing to this provider should be updated first.

Status: 200 OK

{ "success": true }

POST /v1/providers/:id/validate

Re-validate stored credentials for an existing provider account. Updates the isActive flag based on the validation result.

Response

{
  "valid": true,
  "providerType": "SENDGRID"
}

GET /v1/providers/:id/domains

List domain verification status for a provider account.

Response

{
  "data": [
    {
      "id": "dv-uuid",
      "providerAccountId": "pa-uuid",
      "domain": "yourdomain.com",
      "isVerified": true,
      "dnsRecords": [...],
      "createdAt": "2025-01-10T08:30:00Z"
    }
  ]
}