Email keys

Every project with email has its own email API keys. Your app uses one to send, and the same key is the SMTP password for smtp.helipod.io. You can make them in the dashboard, or with these endpoints, which is what a reseller needs to give each customer project its own key.

Who can call them: a Helipod API key with Email API enabled. A key limited to one project manages that project's keys. A whole-account key names the project with an X-Helipod-Project: <projectId> header.

An email key itself, or an AI tool signed in through the MCP server, gets 403 KEY_NOT_ALLOWED here. So a leaked email key or SMTP password can send email for its project, but it cannot make more keys.

The email key object:

{
  "id": "5b1f7d2e-0a4c-4f3e-9d61-2c8b7a9e4f10",
  "name": "Customer Toko Maju",
  "keyPrefix": "hel_3f9a2c1b",
  "status": "active",
  "access": "full",
  "lastUsedAt": "2026-11-02T08:15:00.000Z",
  "expiresAt": null,
  "createdAt": "2026-11-02T07:00:00.000Z"
}

Create a keyCopy Anchor Link

curl -X POST https://mail.helipod.io/api/email/keys \
  -H "Authorization: Bearer hel_your_helipod_key" \
  -H "X-Helipod-Project: 3b0cd5ac-ac26-4012-9b28-17466f73788c" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Customer Toko Maju" }'

{
  "success": true,
  "data": {
    "id": "5b1f7d2e-0a4c-4f3e-9d61-2c8b7a9e4f10",
    "name": "Customer Toko Maju",
    "keyPrefix": "hel_3f9a2c1b",
    "status": "active",
    "access": "full",
    "lastUsedAt": null,
    "expiresAt": null,
    "createdAt": "2026-11-02T07:00:00.000Z",
    "key": "hel_3f9a2c1b..."
  }
}

Store key right away, in your database encrypted or in a secret manager. Helipod keeps only a hash and cannot show it again. If it is lost, revoke it and make a new one.

The project needs email first (404 NO_CONFIG otherwise): start it with POST /email/plan. Each project can hold this many active keys, revoked ones not counted:

Past that the call answers 402 API_KEY_LIMIT_REACHED. The allowance is per project, so an account with many customer projects gets it in each.

Send-only keysCopy Anchor Link

A key made with "access": "send" can only send email and check what it sent:

• POST /email/send and POST /email/send/batch
• SMTP on smtp.helipod.io (it is the password, username apikey)
• GET /email/emails/{id} and GET /email/emails/{id}/events

Every other route answers 403 KEY_SEND_ONLY: plans and renewals, pay-as-you-go, domains, templates, contacts, broadcasts, webhooks, inbound and keys. Use it for a customer or an app that only needs to send, so the key can never buy or renew a plan from your wallet.

curl -X POST https://mail.helipod.io/api/email/keys \
  -H "Authorization: Bearer hel_your_helipod_key" \
  -H "X-Helipod-Project: 3b0cd5ac-ac26-4012-9b28-17466f73788c" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Customer Toko Maju SMTP", "access": "send" }'

Keys made before send-only keys existed, and keys made without access, are full.

List keysCopy Anchor Link

curl https://mail.helipod.io/api/email/keys \
  -H "Authorization: Bearer hel_your_helipod_key" \
  -H "X-Helipod-Project: 3b0cd5ac-ac26-4012-9b28-17466f73788c"

Revoke a keyCopy Anchor Link

curl -X DELETE https://mail.helipod.io/api/email/keys/5b1f7d2e-0a4c-4f3e-9d61-2c8b7a9e4f10 \
  -H "Authorization: Bearer hel_your_helipod_key" \
  -H "X-Helipod-Project: 3b0cd5ac-ac26-4012-9b28-17466f73788c"

{ "success": true, "data": { "revoked": true } }

A key of another project, or an id that does not exist, answers 404.

Example: one key per customerCopy Anchor Link

A reseller with one whole-account Helipod API key (Email API enabled) sets up a customer like this:

1. Create a project for the customer with POST /api/projects on api.helipod.io.
2. Start email in it with POST /email/plan, header X-Helipod-Project: <the new project's id>. Ask with ?dryRun=true first for the price.
3. Add and verify the customer's sending domain with POST /email/domains.
4. Create the customer's key with POST /email/keys and give it to them. If they only need to send (an SMTP password for WordPress or an app), add "access": "send" so the key cannot touch plans or anything that costs money. In their app it is the API key; in WordPress, Laravel or any SMTP client it is the password, with username apikey, host smtp.helipod.io, port 587 (STARTTLS) or 465 (SSL).

The customer's key reaches only their project: their domains, contacts, templates and logs. It cannot read other customers' data and cannot make new keys.