Lumail
Sign up

API Tokens

Learn how to create and use API tokens to authenticate your API requests

API tokens authenticate requests without user credentials. Each lum_ token is scoped to one organization and to a permission set. OAuth CLI sessions stay full-access operators. Existing tokens created before permissions shipped keep full access (*).

Creating an API Token

After lumail auth login, mint a durable token for an app or CI:

lumail tokens create --name "In-app integration"

Defaults to the App preset: subscribers, emails, audience. That is enough for SDK upserts and SMTP. It cannot send campaigns or mint tokens.

lumail tokens create --name "In-app integration" --full
lumail tokens create --name sender --preset sender
lumail tokens create --name custom --permissions subscribers,audience

Reuse only works when the same name and the same permission set already exist. A full token named In-app integration will not be returned for an App create — that is 409 token_permission_mismatch. Use --no-reuse or a different name. The lum_ secret is printed once. lumail tokens list shows names, last-4, and permissions.

Step 1: Navigate to API Tokens Page

  1. Log in to your Lumail account
  2. Select your organization from the sidebar
  3. Go to Settings → API Tokens
  4. Click the Generate Token button

Step 2: Name Your Token and pick permissions

Give your token a descriptive name and a permission preset. The dashboard defaults to App. Full access is an explicit choice. Permissions cannot be edited later — rotate the token instead.

Presets:

  • App — subscribers, emails, audience
  • Marketing editor — App plus campaigns, analytics, workflows
  • Sender — marketing editor plus campaign send/schedule
  • Full — everything, including tokens and domains
  • Custom — any set of groups

A missing group returns 403 with code: "missing_permission" and required set to the group (not a 404).

Give your token a descriptive name to help you identify its purpose later:

  • Production API - For production applications
  • Development - For local development
  • Integration Testing - For CI/CD pipelines
  • Mobile App - For mobile applications

Step 3: Save Your Token

IMPORTANT: After creation, your token will be displayed only once. Copy and store it securely immediately.

lum_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

The token format is: lum_ followed by a 64-character random string.

Using Your API Token

Authentication Header

All API requests must include the token in the Authorization header using the Bearer authentication scheme:

Authorization: Bearer lum_your_token_here

Basic Request Structure

Every API request should include:

  1. Authorization Header - Your API token with Bearer prefix
  2. Content-Type Header - Usually application/json
  3. Request Body - For POST/PUT/PATCH requests (JSON format)

Usage Examples

Example 1: Sending a Transactional Email

const response = await fetch("https://lumail.io/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: "Bearer lum_your_token_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "[email protected]",
    subject: "Welcome!",
    content: "Hello {{name}}, welcome to our platform!",
    from: "[email protected]",
  }),
});

const data = await response.json();
console.log(data);

Example 2: Creating a Subscriber

const response = await fetch("https://lumail.io/api/v1/subscribers", {
  method: "POST",
  headers: {
    Authorization: "Bearer lum_your_token_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "[email protected]",
    name: "Jane Smith",
    tags: ["newsletter", "promotional"],
  }),
});

const data = await response.json();
console.log(data);

Example 3: Listing All Tags

const response = await fetch("https://lumail.io/api/v1/tags", {
  method: "GET",
  headers: {
    Authorization: "Bearer lum_your_token_here",
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data.tags);

Example 4: Error Handling

Always implement proper error handling for API requests:

try {
  const response = await fetch("https://lumail.io/api/v1/subscribers/sub_123", {
    method: "GET",
    headers: {
      Authorization: "Bearer lum_your_token_here",
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    const error = await response.json();
    console.error("API Error:", error.message);
    return;
  }

  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error("Network Error:", error);
}

Best Practices

Security

  1. Never commit tokens to version control - Use environment variables
  2. Store tokens securely - Use secret management services
  3. Rotate tokens regularly - Generate new tokens periodically
  4. Use separate tokens - Different tokens for dev, staging, and production
  5. Delete unused tokens - Remove tokens you're no longer using

Environment Variables

Store your API token in environment variables:

# .env.local (DO NOT commit this file)
LUMAIL_API_TOKEN=lum_your_token_here

Then use it in your code:

const response = await fetch("https://lumail.io/api/v1/subscribers", {
  headers: {
    Authorization: `Bearer ${process.env.LUMAIL_API_TOKEN}`,
    "Content-Type": "application/json",
  },
});

Rate Limiting

API requests are rate-limited based on your subscription plan. See Rate Limits for full details. Implement exponential backoff for failed requests:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return response;
    }

    if (response.status === 429) {
      // Rate limited - wait and retry
      const waitTime = Math.pow(2, i) * 1000;
      await new Promise((resolve) => setTimeout(resolve, waitTime));
      continue;
    }

    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  throw new Error("Max retries exceeded");
}

Common Errors

401 Unauthorized - Missing Authorization Header

{
  "message": "Missing or invalid Authorization header"
}

Solution: Ensure you're including the Authorization: Bearer <token> header in your request.

401 Unauthorized - Invalid API Token

{
  "message": "Invalid API token"
}

Solution:

  • Verify your token is correct (no extra spaces or characters)
  • Check if the token has been deleted from the settings page
  • Generate a new token if necessary

404 Not Found - Resource Not Found

{
  "error": "Subscriber not found"
}

Solution: Verify the resource ID exists in your organization.

403 Forbidden - Missing Permission

{
  "message": "Missing permission: send",
  "code": "missing_permission",
  "required": "send"
}

Solution: Mint a token that includes the required group (--preset sender / --full, or a custom --permissions list). Permissions cannot be edited — rotate the token.

The SDK throws LumailPermissionError with required. The CLI prints the group and a mint hint.

400 Bad Request - Validation Error

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Solution: Check your request body matches the expected schema for the endpoint.

Managing Tokens

Viewing Active Tokens

Go to Settings → API Tokens to see all active tokens for your organization:

  • Token name
  • Creation date
  • Last used date (if applicable)
  • Last 7 days of actions (REST, v2 tools, MCP) with success / warning / error messages. Rows older than 7 days are deleted automatically. The raw lum_ secret is never stored on a log row.

Deleting Tokens

To delete a token:

  1. Navigate to Settings → API Tokens
  2. Find the token you want to delete
  3. Click the delete icon
  4. Confirm the deletion

Note: Deleting a token immediately revokes access. Any applications using that token will fail authentication.

Token Rotation

For security best practices, rotate your tokens periodically:

  1. Generate a new token
  2. Update your applications to use the new token
  3. Test that the new token works
  4. Delete the old token

Organization Scope

Each API token is scoped to a specific organization. The token provides access to:

  • All subscribers in your organization
  • All campaigns and emails
  • All tags and custom fields
  • All analytics and reports
  • Organization settings (where applicable)

Tokens cannot access:

  • Other organizations' data
  • User account settings
  • Billing information beyond basic plan details

Now that you have your API token set up, explore the available API endpoints:

Tutorials

PreviousErrorsNextTypeScript SDK