`https://lumail.io/api/v1/subscribers` Add a new subscriber to your email list or update an existing one. Subscribers are identified by their email address. ## Response - **Success (200 OK)** - Returns the subscriber object. - **Error (400 Bad Request)** - Generic message if the email is invalid or if the subscriber limit is reached. - **Error (402 Payment Required)** - Indicates that the subscriber limit is reached. ## Response Fields | Field | Type | Description | | ------------------------------ | -------------- | ------------------------------------------------------------------------------- | | `success` | boolean | Indicates if the operation was successful | | `subscriber` | object | The subscriber object with all its properties | | `subscriber.id` | string | Unique identifier for the subscriber | | `subscriber.email` | string | Email address of the subscriber | | `subscriber.name` | string or null | Name of the subscriber (if provided) | | `subscriber.phone` | string or null | Phone number of the subscriber (if provided) | | `subscriber.unsubscribeReason` | string or null | Reason provided when unsubscribing (if applicable) | | `subscriber.status` | string | Current status of the subscriber (e.g., "SUBSCRIBED", "UNSUBSCRIBED", "BANNED") | | `subscriber.clickCount` | number | Total number of clicks from this subscriber | | `subscriber.openCount` | number | Total number of email opens from this subscriber | | `subscriber.revenue` | number | Total revenue attributed to this subscriber | | `subscriber.organizationId` | string | ID of the organization this subscriber belongs to | | `subscriber.ipAddress` | string or null | IP address of the subscriber (captured at signup) | | `subscriber.country` | string or null | ISO 3166-1 alpha-2 country code (e.g., "US", "FR", "CH") | | `subscriber.createdAt` | string | ISO timestamp when the subscriber was created | | `subscriber.updatedAt` | string | ISO timestamp when the subscriber was last updated | | `subscriber.fields` | array | Custom field values associated with this subscriber | | `subscriber.fields[].id` | string | Unique identifier for the field | | `subscriber.fields[].name` | string | Name of the field | | `subscriber.fields[].value` | string | Value of the field | | `subscriber.tags` | array | Tags associated with this subscriber | | `subscriber.tags[].id` | string | Unique identifier for the tag | | `subscriber.tags[].name` | string | Name of the tag | ## Request Schema | Field | Type | Default | Description | | ------------------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | string | required | Email address of the subscriber | | `name` | string | optional | Name of the subscriber | | `phone` | string | optional | Phone number of the subscriber | | `tags` | string[] | `[]` | Tag names to assign to the subscriber | | `fields` | object | optional | Custom field values (key-value pairs). Note: `email`, `name`, and `phone` are reserved field names and will be ignored if used. | | `replaceTags` | boolean | `false` | If `true`, replaces all existing tags with the provided ones | | `resubscribe` | boolean | `true` | If `true`, resubscribes the user if they were previously unsubscribed. For POST, this defaults to `true` since the user is actively subscribing | | `triggerWorkflows` | boolean | `true` | If `false`, skip triggering workflows even if subscriber's tags match workflow triggers. Useful for bulk imports or syncing data without triggering automations | | `skipDoubleOptIn` | boolean | `false` | If `true`, create the contact as `SUBSCRIBED` even when organization double opt-in is on. No confirmation email or token. Does not write `confirmedAt`. Does not resubscribe `UNSUBSCRIBED` unless `resubscribe` is also true. Use for trusted backends (checkout, server import), not public forms. | | `ipAddress` | string | optional | IP address of the subscriber. Used to auto-detect country if `country` is not provided | | `country` | string | optional | ISO 3166-1 alpha-2 country code (e.g., "US", "FR", "CH"). Auto-detected from `ipAddress` if not provided | ### Reserved Field Names The following field names are reserved and cannot be used in the `fields` object: - `email` - Use the dedicated `email` parameter instead - `name` - Use the dedicated `name` parameter instead - `phone` - Use the dedicated `phone` parameter instead If you attempt to use a reserved field name, it will be ignored and a warning will be returned in the response. ## Usage Example Use this API endpoint to: - Add new subscribers to your email list from external forms or applications - Import subscribers from other systems - Update existing subscriber information - Add custom fields for personalization - Assign tags for segmentation and targeting - Track subscriber information for analytics and reporting ## Related Documentation - [Tags API](/docs/api-reference/api-tags-get) - Manage subscriber tags - [Add Tags to Subscriber](/docs/api-reference/api-subscriber-tags-post) - Add tags after creation - [Verify Email](/docs/api-reference/api-email-verify-post) - Validate emails before adding - [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in) - Native confirmation before campaigns - [Workflows](/docs/workflows) - Trigger automations when subscribers are added - [V0 Capture Page](/docs/tutorials/v0-capture-page) - Build capture forms to add subscribers - [Variables](/docs/features/variables) - Use subscriber data in emails ## API Reference **Method:** POST **Endpoint:** /api/v1/subscribers ### SDK ```ts import { Lumail } from "lumail"; const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" }); const { subscriber } = await lumail.subscribers.create({ email: "subscriber@example.com", name: "John Doe", tags: ["newsletter"], }); console.log(subscriber); ``` ### cURL ```bash curl -X POST https://lumail.io/api/v1/subscribers \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"email": "subscriber@example.com"}' ``` ### JavaScript ```javascript const response = await fetch('https://lumail.io/api/v1/subscribers', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ email: 'subscriber@example.com', name: 'John Doe', tags: ['newsletter'] }), }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests url = "https://lumail.io/api/v1/subscribers" headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } payload = { "email": "subscriber@example.com", "name": "John Doe", "tags": ["newsletter"] } response = requests.post(url, json=payload, headers=headers) data = response.json() print(data) ``` ### Success Response ```json { "success": true, "subscriber": { "id": "sub_TTYPR5tWDh", "email": "demo@gmail.com", "name": null, "phone": null, "status": "SUBSCRIBED", "unsubscribeReason": null, "clickCount": 0, "openCount": 0, "revenue": 0, "organizationId": "HEnp-DaJnmI", "createdAt": "2025-04-27T04:49:56.381Z", "updatedAt": "2025-04-27T04:49:56.381Z", "tags": [ { "id": "tag_JqaddtEx7z", "name": "demo1" }, { "id": "tag_rdEPhyjnfA", "name": "demo2" } ], "fields": [ { "id": "fld_vU4hI9WrWb", "name": "special-field", "value": "My special value" } ] } } ``` ### Error Response ```json { "message": "We can't subscribe this email." } ```