Authentication

Exchange your service account credentials for a short-lived token, then use it on every API call.

Credentials

Create a service account in the portal to get a pair of credentials:

If you lose the secret you cannot recover it, but you can regenerate the pair from the portal. Regenerating invalidates the old secret immediately.

Get a token

Exchange the credentials for a JWT. Tokens are valid for 1 hour.

curl -X POST https://api.mailverick.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key_id": "mvk_id_xxxxxxxxxx",
    "api_key_secret": "mvk_sec_xxxxxxxxxx"
  }'

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use the token

Pass it in the Authorization header on every call to a protected endpoint.

curl -X POST https://api.mailverick.com/v1/send-email \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Exchange a new token before the old one expires. Do not request one per API call: the exchange is deliberately slower than a normal request, and a token is reusable for its full hour. Our Node.js SDK handles the exchange and refresh for you.

Permissions

Each service account carries its own set of permissions, so you can scope a key to exactly what it needs. A key embedded in a signup form should not be able to send mail.

A call to an endpoint the key is not scoped for returns 403, whatever the token's other permissions are. You can create up to 3 service accounts per organization.

Errors

SMTP

SMTP submission does not use tokens. Authenticate with the same credentials directly, using the key ID as the username and the secret as the password. See Send Email for host and port settings.

What's next

With a token in hand you can send email or validate an address.