Mailer API

Requirements:

• Make sure the mailer is configured for your environment.
• Make sure you have generated an Environment-level API Key.

Send an email.

interface Request {
  to: string
  from: string
  subject: string
  body: string
  replyTo?: string // e.g. the visitor who filled in a contact form
}

interface Response {
  ok: boolean
  delivered: boolean // false when the environment has no SMTP configuration
}

An environment without a mailer still records the email without sending it, so ok alone does not mean the message was handed to an SMTP server. Check delivered when you are using this endpoint to verify that a mailer works.

# Example

curl -X POST \
     -H 'Authorization: <api_key>' \
     -H 'Content-Type: application/javascript' \
     'https://api.stormkit.io/v1/mail' \
     -d '{ "to": "joe@example.org", "from": "Jane Doe <jane@example.org>", "subject": "Hello Joe", "body": "Hi,<br/>How are you?" }'

Return the SMTP configuration of an environment.

The password is never returned. When one is stored, password contains the placeholder ****-****-****-****; when no mailer is configured at all, config is null.

interface Response {
  config: {
    host: string
    port: string
    username: string
    password: string // always the placeholder
    useDefault: boolean // true when the environment uses the instance's default mailer
  } | null
  defaultAvailable: boolean // whether the instance has a default mailer
}

# Example

curl -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/mailer/config?appId=<app_id>&envId=<env_id>'

Update the SMTP configuration of an environment. Only the fields you provide are changed; omitted fields keep their stored value.

password is write-only. Omit it — or send the ****-****-****-**** placeholder returned by the GET endpoint — to keep the stored password. host, username and a password must all be set before email can be sent.

Changing smtpHost or username clears the stored password, because a credential you cannot read must not follow the configuration to a different server or account. Send a new password in the same request when you change either; otherwise the request is rejected with Password is a required field. and nothing is written.

On self-hosted instances, send useDefault: true to use the instance's default mailer, set up by the instance admin, instead. The environment's own SMTP settings are dropped, and emails that set no sender go out from the instance's From address. The request fails with a 400 when the instance has no default mailer. Send useDefault: false with a full set of SMTP settings to switch back.

interface Request {
  smtpHost?: string
  smtpPort?: string // defaults to 587
  username?: string
  password?: string
  useDefault?: boolean
}

interface Response {
  config: {
    host: string
    port: string
    username: string
    password: string // always the placeholder
    useDefault: boolean
  }
  defaultAvailable: boolean
}

# Example

curl -X POST \
     -H 'Authorization: <api_key>' \
     -H 'Content-Type: application/json' \
     'https://api.stormkit.io/v1/mailer/config' \
     -d '{ "appId": "<app_id>", "envId": "<env_id>", "smtpHost": "smtp.example.org", "smtpPort": "587", "username": "jane@example.org", "password": "<smtp_password>" }'

Return the last 100 emails recorded for an environment, newest first.

Message bodies are not included, and recipient addresses are masked (j***@example.com). The mailer log stores magic-link emails verbatim, so a body contains a sign-in link — single-use and valid for 15 minutes — and the full recipient list is the app's end-user mailing list. The remaining metadata is enough to confirm that an email was sent. Full bodies and addresses remain visible in the dashboard, behind a session login.

interface Response {
  emails: Array<{
    id: string
    envId: string
    from: string
    to: string
    subject: string
    sentAt: number
  }>
}

# Example

curl -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/mailer/emails?appId=<app_id>&envId=<env_id>'