Overview

Helipod Email is a sending (and optional receiving) service for your Helipod projects. With an email API key you can send single and batch messages, manage templates, sending domains, contacts, segments, topics and broadcasts, read delivery logs and analytics, and receive events on your own webhook.

Base URLCopy Anchor Link

https://mail.helipod.io/api/email

Every path in this section is relative to that base URL. For example, POST /send means POST https://mail.helipod.io/api/email/send.

AuthenticationCopy Anchor Link

Send your email API key as a Bearer token on every request:

Authorization: Bearer your_email_api_key

How email API keys work:

• Created in the dashboard. Open your project, go to the Email section and create a key under API keys. The full key is shown once; store it in a secret manager.
• Format. Keys start with hel_ followed by 48 hexadecimal characters. The dashboard shows the first 12 characters (the key prefix) so you can tell keys apart.
• Bound to one project. A key belongs to the email service of exactly one project. You never pass a project id: every request made with the key acts on that project's domains, templates, contacts and logs.
• Only its own project. Ids of another project (even one you own) answer 404, and job lists show only the project's own jobs.
• Plans, with care. Keys can read the plan, buy, renew or change it and its inbox add-ons (also after the plan has ended), with ?dryRun=true for the price and a required Idempotency-Key on the real call. See Plan and add-ons.
• Dashboard only. Creating or revoking email keys, cancelling a plan, the auto-renew and pay-as-you-go switches, and webmail passwords of mailboxes answer 403 KEY_NOT_ALLOWED to a key.
• No scopes. Within its project a key can use every endpoint documented here. Use separate keys per integration so you can revoke one without affecting the others.
• Optional expiry. A key can be created with an expiry (1 to 3650 days). Expired keys return 401 API_KEY_EXPIRED. Revoked keys return 401 INVALID_API_KEY.
• Or a Helipod API key. A Helipod API key with Email API enabled works too, and so does an AI tool signed in through the MCP server with it ticked. A key limited to one project acts on that project. A whole-account key names the project with an X-Helipod-Project: <projectId> header, unless only one of your projects has email (400 PROJECT_REQUIRED otherwise). A Helipod key without the Email API answers 403 SCOPE_NOT_ALLOWED. SMTP still needs an email API key.

Response envelopeCopy Anchor Link

Every response uses the same envelope.

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

{ "success": false, "error": "Human readable message", "code": "MACHINE_CODE" }

Branch on code, not on the message text. Messages can change; codes do not. One exception adds a data field to a failure: a batch send in which every message failed (see Sending). The full list of codes is in Limits and errors.

Background jobsCopy Anchor Link

Several operations run in the background and answer 202 Accepted with a jobId (for example adding a domain, creating a template, or sending). Poll the job to see how it ended.

curl https://mail.helipod.io/api/email/jobs/eml_8f21c0a94d7b4c2e9a1f \
  -H "Authorization: Bearer your_email_api_key"

{
  "success": true,
  "data": {
    "jobId": "eml_8f21c0a94d7b4c2e9a1f",
    "type": "verify_domain",
    "status": "completed",
    "result": { },
    "errorMessage": null,
    "attempts": 1,
    "createdAt": "2026-10-16T09:14:03.221Z",
    "startedAt": "2026-10-16T09:14:03.540Z",
    "completedAt": "2026-10-16T09:14:05.102Z"
  }
}

Returns 404 JOB_NOT_FOUND for an unknown id.

PaginationCopy Anchor Link

List endpoints that can grow large are cursor-paginated. Pass limit and, for the next page, the nextCursor from the previous response as cursor. nextCursor is null on the last page. Paginated lists nest the rows one level deeper:

{ "success": true, "data": { "data": [ ], "nextCursor": "2026-10-16T09:14:03.221544Z" } }

Quick startCopy Anchor Link

export HELIPOD_EMAIL_KEY="your_email_api_key"

curl -X POST https://mail.helipod.io/api/email/domains \
  -H "Authorization: Bearer $HELIPOD_EMAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

curl https://mail.helipod.io/api/email/domains/3f2a9c4e-1b7d-4e0a-9c55-2d8f6b1a7e10 \
  -H "Authorization: Bearer $HELIPOD_EMAIL_KEY"

curl -X POST https://mail.helipod.io/api/email/domains/3f2a9c4e-1b7d-4e0a-9c55-2d8f6b1a7e10/verify \
  -H "Authorization: Bearer $HELIPOD_EMAIL_KEY"

curl -X POST https://mail.helipod.io/api/email/send \
  -H "Authorization: Bearer $HELIPOD_EMAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up.</p>",
    "text": "Thanks for signing up."
  }'

SectionsCopy Anchor Link