Create Subscriber

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 - Manage subscriber tags
• Add Tags to Subscriber - Add tags after creation
• Verify Email - Validate emails before adding
• Enable Double Opt-In - Native confirmation before campaigns
• Workflows - Trigger automations when subscribers are added
• V0 Capture Page - Build capture forms to add subscribers
• Variables - Use subscriber data in emails