API reference

Auth

Create an account or log in. Each returns the session token the management API uses. See Server-side login for a guided walk-through.

Auth: Public · Base URL: https://api.mailkite.dev

Endpoints

Each row expands to its request and response schema. The address bar follows along, so any endpoint can be linked to directly.

POST /api/auth/signup Create an account. Returns a session token.

Create an account. Returns a session token.

Request body

signup-request.json

Field	Type	Notes
email req	string	Account email — receives the verification link.
password req	string	Account password.
ref	string	Referral code of the account that referred this signup, when any.
channel	string	Distribution-channel slug the signup came through (e.g. wordpress-plugin) — the where to ref's who. Invalid values are dropped, never an error.
referrer	string	First-touch landing referrer URL (external document.referrer captured on first visit). Invalid values are dropped, never an error.

signup-request.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/signup-request.json",
  "title": "Signup request body",
  "type": "object",
  "required": [
    "email",
    "password"
  ],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "description": "Account email — receives the verification link.",
      "examples": [
        "ada@example.com"
      ]
    },
    "password": {
      "type": "string",
      "description": "Account password."
    },
    "ref": {
      "type": "string",
      "description": "Referral code of the account that referred this signup, when any."
    },
    "channel": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_-]{0,31}$",
      "description": "Distribution-channel slug the signup came through (e.g. wordpress-plugin) — the where to ref's who. Invalid values are dropped, never an error."
    },
    "referrer": {
      "type": "string",
      "description": "First-touch landing referrer URL (external document.referrer captured on first visit). Invalid values are dropped, never an error."
    }
  }
}

Response body

auth-token-response.json

Signup, login, and OAuth sign-in all resolve to this: a session token plus the account it belongs to. Send the token as `Authorization: Bearer <token>` on /api/* calls.

Field	Type	Notes
token req	string	Session JWT.
user req	object	The signed-in account.
user.id req	string	Account id (usr_…).
user.email req	string	Account email.
user.isAdmin req	boolean	True for MailKite staff accounts.
user.emailVerified req	boolean	Whether the account email has been confirmed.
user.avatarUrl	string · null	Avatar image URL, when the identity provider supplied one.

An actual response, recorded from the conformance suite.

response.json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfN0ZqM01uUXcifQ.signature",
  "user": {
    "id": "usr_7Fj3MnQw",
    "email": "ada@example.com",
    "isAdmin": false,
    "emailVerified": true,
    "avatarUrl": null
  }
}

auth-token-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/auth-token-response.json",
  "title": "Auth token response",
  "description": "Signup, login, and OAuth sign-in all resolve to this: a session token plus the account it belongs to. Send the token as `Authorization: Bearer <token>` on /api/* calls.",
  "type": "object",
  "required": [
    "token",
    "user"
  ],
  "properties": {
    "token": {
      "type": "string",
      "description": "Session JWT.",
      "examples": [
        "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
      ]
    },
    "user": {
      "type": "object",
      "required": [
        "id",
        "email",
        "isAdmin",
        "emailVerified"
      ],
      "description": "The signed-in account.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Account id (usr_…).",
          "examples": [
            "usr_7Fj3MnQw"
          ]
        },
        "email": {
          "type": "string",
          "description": "Account email.",
          "examples": [
            "ada@example.com"
          ]
        },
        "isAdmin": {
          "type": "boolean",
          "description": "True for MailKite staff accounts."
        },
        "emailVerified": {
          "type": "boolean",
          "description": "Whether the account email has been confirmed."
        },
        "avatarUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "Avatar image URL, when the identity provider supplied one."
        }
      }
    }
  }
}

POST /api/auth/login Log in with email + password. Returns a session token.

Request body

Field	Type	Notes
email req	string	Account email.
password req	string	Account password.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/login-request.json",
  "title": "Login request body",
  "type": "object",
  "required": [
    "email",
    "password"
  ],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "description": "Account email.",
      "examples": [
        "ada@example.com"
      ]
    },
    "password": {
      "type": "string",
      "description": "Account password."
    }
  }
}

Response body

auth-token-response.json

Signup, login, and OAuth sign-in all resolve to this: a session token plus the account it belongs to. Send the token as `Authorization: Bearer <token>` on /api/* calls.

Field	Type	Notes
token req	string	Session JWT.
user req	object	The signed-in account.
user.id req	string	Account id (usr_…).
user.email req	string	Account email.
user.isAdmin req	boolean	True for MailKite staff accounts.
user.emailVerified req	boolean	Whether the account email has been confirmed.
user.avatarUrl	string · null	Avatar image URL, when the identity provider supplied one.

An actual response, recorded from the conformance suite.

response.json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfN0ZqM01uUXcifQ.signature",
  "user": {
    "id": "usr_7Fj3MnQw",
    "email": "ada@example.com",
    "isAdmin": false,
    "emailVerified": true,
    "avatarUrl": null
  }
}

auth-token-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/auth-token-response.json",
  "title": "Auth token response",
  "description": "Signup, login, and OAuth sign-in all resolve to this: a session token plus the account it belongs to. Send the token as `Authorization: Bearer <token>` on /api/* calls.",
  "type": "object",
  "required": [
    "token",
    "user"
  ],
  "properties": {
    "token": {
      "type": "string",
      "description": "Session JWT.",
      "examples": [
        "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
      ]
    },
    "user": {
      "type": "object",
      "required": [
        "id",
        "email",
        "isAdmin",
        "emailVerified"
      ],
      "description": "The signed-in account.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Account id (usr_…).",
          "examples": [
            "usr_7Fj3MnQw"
          ]
        },
        "email": {
          "type": "string",
          "description": "Account email.",
          "examples": [
            "ada@example.com"
          ]
        },
        "isAdmin": {
          "type": "boolean",
          "description": "True for MailKite staff accounts."
        },
        "emailVerified": {
          "type": "boolean",
          "description": "Whether the account email has been confirmed."
        },
        "avatarUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "Avatar image URL, when the identity provider supplied one."
        }
      }
    }
  }
}

POST /api/auth/google Sign in with a Google auth code. Returns a session token.

Request body

google-auth-request.json

Field	Type	Notes
code req	string	One-time authorization code from Google's redirect.
redirectUri req	string	The redirect URI the code was issued to — must match a registered URI.
ref	string	Referral code, when any (Google sign-in doubles as signup).

google-auth-request.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/google-auth-request.json",
  "title": "Google sign-in request body",
  "type": "object",
  "required": [
    "code",
    "redirectUri"
  ],
  "additionalProperties": false,
  "properties": {
    "code": {
      "type": "string",
      "description": "One-time authorization code from Google's redirect."
    },
    "redirectUri": {
      "type": "string",
      "description": "The redirect URI the code was issued to — must match a registered URI.",
      "examples": [
        "https://mailkite.dev/auth/google/callback"
      ]
    },
    "ref": {
      "type": "string",
      "description": "Referral code, when any (Google sign-in doubles as signup)."
    }
  }
}

Response body

auth-token-response.json

Signup, login, and OAuth sign-in all resolve to this: a session token plus the account it belongs to. Send the token as `Authorization: Bearer <token>` on /api/* calls.

Field	Type	Notes
token req	string	Session JWT.
user req	object	The signed-in account.
user.id req	string	Account id (usr_…).
user.email req	string	Account email.
user.isAdmin req	boolean	True for MailKite staff accounts.
user.emailVerified req	boolean	Whether the account email has been confirmed.
user.avatarUrl	string · null	Avatar image URL, when the identity provider supplied one.

An actual response, recorded from the conformance suite.

response.json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfN0ZqM01uUXcifQ.signature",
  "user": {
    "id": "usr_7Fj3MnQw",
    "email": "ada@example.com",
    "isAdmin": false,
    "emailVerified": true,
    "avatarUrl": null
  }
}

auth-token-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/auth-token-response.json",
  "title": "Auth token response",
  "description": "Signup, login, and OAuth sign-in all resolve to this: a session token plus the account it belongs to. Send the token as `Authorization: Bearer <token>` on /api/* calls.",
  "type": "object",
  "required": [
    "token",
    "user"
  ],
  "properties": {
    "token": {
      "type": "string",
      "description": "Session JWT.",
      "examples": [
        "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
      ]
    },
    "user": {
      "type": "object",
      "required": [
        "id",
        "email",
        "isAdmin",
        "emailVerified"
      ],
      "description": "The signed-in account.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Account id (usr_…).",
          "examples": [
            "usr_7Fj3MnQw"
          ]
        },
        "email": {
          "type": "string",
          "description": "Account email.",
          "examples": [
            "ada@example.com"
          ]
        },
        "isAdmin": {
          "type": "boolean",
          "description": "True for MailKite staff accounts."
        },
        "emailVerified": {
          "type": "boolean",
          "description": "Whether the account email has been confirmed."
        },
        "avatarUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "Avatar image URL, when the identity provider supplied one."
        }
      }
    }
  }
}