SMTP Provider API Documentation

This document explains the SMTP Provider APIs used for token authentication, domain setup, DNS verification, sender management, template management, mailing list creation, campaign management, and welcome email sending.

All protected endpoints require a Bearer token generated by the smtp-token-generate API. Most protected APIs also require user_id. The user_id must match the authenticated token user, otherwise the API returns a wrong user id error.

1. Generate token using /smtp-token-generate.
2. Save the returned token and user.id.
3. Add sending domain using /v1/smtp-domain-add.
4. Get DNS records using /v1/smtp-domain-view.
5. Add DNS records in the domain DNS provider.
6. Verify domain using /v1/smtp-domain-verify.
7. Add sender email using /v1/smtp-domain-sender-add.
8. Send sender verification email using /v1/smtp-domain-sender-verify when needed.
9. Create or select template using smtp-template APIs.
10. Create mailing list using /v1/smtp-mailing-add.
11. Load campaign options using /v1/smtp-campaign-create.
12. Create campaign using /v1/smtp-campaign-store.
13. View campaigns using /v1/smtp-campaign-index.
14. Pause, resume, edit, or update campaigns when required.

Public token endpoint:

Accept: application/json

Content-Type: application/json

Protected endpoints:

Accept: application/json

Content-Type: application/json

Authorization: Bearer YOUR_TOKEN_HERE

Token API Success Response

{
    "status": true,
    "message": "Token Created Successfully",
    "token": "1|plain-text-token",
    "user": {
        "id": 123,
        "name": "Demo User",
        "email": "user@example.com"
    }
}

Protected API Success Response

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

Validation Error Response

{
    "success": false,
    "data": [
        "The user id field is required."
    ]
}

Authentication Error Examples

• 401: Unauthenticated.
• 401: Invalid token.
• 403: Wrong user id.
• 422: Validation failed.

Method: POST

Full URL: https://app.smtpprovider.com/api/smtp-token-generate

Purpose: Authenticates a user by email and password and returns an API Bearer token.

Request Fields

• email: Required. Registered user email address.
• password: Required. User password.

Sample Request

{
    "email": "user@example.com",
    "password": "secret-password"
}

Sample Success Response

{
    "status": true,
    "message": "Token Created Successfully",
    "token": "1|plain-text-token",
    "user": {
        "id": 123,
        "name": "Demo User",
        "email": "user@example.com"
    }
}

Sample Error Response

{
    "status": false,
    "message": "Invalid email or password"
}

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-domain-add

Purpose: Adds a sending domain and creates DKIM, SPF, SPF subdomain, DMARC, MX, and A record entries for DNS setup.

Request Fields

• user_id: Required. Authenticated user id.
• domain_name: Required. Fully qualified domain name, for example example.com. Must be unique in DKIM records.

Sample Request

{
    "user_id": 123,
    "domain_name": "example.com"
}

Sample Success Response

{
    "success": true,
    "data": {
        "success": true,
        "domain": {
            "id": 10,
            "domain_name": "example.com",
            "host": "smtp._domainkey.example.com",
            "selector": "smtp",
            "public_key": "v=DKIM1; h=sha256; k=rsa; p=..."
        }
    }
}

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-domain-list?user_id=123

Purpose: Lists all sending domains for the authenticated user, newest first.

Query Fields:

• user_id: Required. Authenticated user id.

Response Data Key: domains

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-domain-view?user_id=123&domain_name=example.com

Purpose: Returns all DNS records that must be added for a domain.

Query Fields:

• user_id: Required. Authenticated user id.
• domain_name: Required. Domain name to view.

Response Data Keys:

• domains: DKIM records.
• spf: SPF TXT record for root domain.
• spf_subdomain: SPF TXT record for client subdomain.
• dmarc: DMARC TXT record.
• mx_record: MX record.
• a_record: A record.

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-domain-verify?user_id=123&domain_name=example.com

Purpose: Verifies DNS records against generated DKIM, SPF, DMARC, MX, and A record values.

Query Fields:

• user_id: Required. Authenticated user id.
• domain_name: Required. Domain name to verify.

Sample Success Response

{
    "success": true,
    "data": {
        "success": true,
        "message": "Verified Successfully"
    }
}

Common Error Messages

• Dkim generating status is pending. After Dkim generate is finished, you can verify.
• Public Key not found. Please contact your admin.
• Dkim could not find in DNS server.
• Dkim could not verify.

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-sender-list?user_id=123

Purpose: Lists sender email identities for the authenticated user.

Query Fields:

• user_id: Required. Authenticated user id.

Response Data Key: sender_lists

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-domain-sender-add

Purpose: Adds a sender email for an existing domain. The current API creates the sender as active and verified.

Request Fields

• user_id: Required. Authenticated user id.
• domain_name: Required. Existing domain name.
• sender_name: Required. Display name for the sender.
• from_email: Required. Sender email address. Must be unique for the domain.

Sample Request

{
    "user_id": 123,
    "domain_name": "example.com",
    "sender_name": "Demo Team",
    "from_email": "news@example.com"
}

Response Data Key: sender

Common Error Messages

• Domain not found.
• From Email already exist.Use different email address.

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-domain-sender-verify

Purpose: Sends a verification email to an existing sender address.

Request Fields

• user_id: Required. Authenticated user id.
• from_email: Required. Existing sender email address.

Sample Success Message: Verification Mail Sent Successfully

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-template-index?user_id=123

Purpose: Lists all templates created by the authenticated user.

Response Data Key: templates

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-template-default

Purpose: Lists active default templates, ordered newest first and paginated by 100 records.

Response Data Key: default_templates

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-template-show?user_id=123&template_id=456

Purpose: Shows one template owned by the authenticated user.

Query Fields:

• user_id: Required. Authenticated user id.
• template_id: Required. Existing template id.

Response Data Key: templates

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-template-add

Purpose: Creates a new email template for the authenticated user.

Request Fields

• user_id: Required. Authenticated user id.
• name: Required. Template name. Must be unique per user.
• html_body: Required. HTML email content.
• active: Required. Template active flag, usually true/false or 1/0.

Sample Request

{
    "user_id": 123,
    "name": "Welcome Template",
    "html_body": "<h1>Welcome</h1>",
    "active": true
}

Response Data Key: template

Common Error Messages

• Template name alrady use.Use different template name.
• User Ga not found.

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-template-update

Purpose: Updates an existing template owned by the authenticated user.

Request Fields

• user_id: Required. Authenticated user id.
• template_id: Required. Existing template id.
• name: Required. Template name.
• html_body: Required. Updated HTML email content.
• active: Required. Template active flag.

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-mailing-list?user_id=123

Purpose: Lists mailing lists for the authenticated user.

Response Data Key: mailing_list

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-mailing-add

Purpose: Creates a mailing list.

Request Fields

• user_id: Required. Authenticated user id.
• name: Required. Mailing list name. Must be unique per user.

Sample Request

{
    "user_id": 123,
    "name": "Newsletter Subscribers"
}

Response Data Key: mailing

Common Error Messages

• Mailing name already use.Use different Mailing name.
• User Application not found.
• application api key not found.
• Mailing could not created.something wrong.

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-campaign-index?user_id=123

Purpose: Lists campaigns with mailing list, delivery, application, and content details.

Response Data Key: campaigns

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-campaign-create?user_id=123

Purpose: Returns all selectable data needed before creating a campaign.

Response Data Keys:

• senderDetails: Verified sender email options.
• templates: Active template options.
• url_domains: Tracking URL domain options.
• vmtas: VMTA options.
• mailing_lists: Active finished mailing lists with subscribers.
• bounce_email_id: Bounce email options.
• speed: Campaign sending speed.

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-campaign-store

Purpose: Creates a scheduled campaign.

Request Fields

• user_id: Required. Authenticated user id.
• template_id: Required. Existing template id.
• mailing_list_id: Required. Mailing list id returned from smtp-campaign-create or smtp-mailing-list.
• campaign_name: Required. Campaign name.
• begins_at: Required. Campaign scheduled date and time. Format: YYYY-MM-DD HH:MM:SS, for example 2026-05-06 18:00:00.
• segment: Required. Segmentation criteria.
• all_request: Required. Object containing campaign content and delivery details.

all_request Fields (send these keys inside the all_request object):

• subject: Required. Email subject.
• html_body: Required. HTML email body.
• text_body: Required. Plain text body.
• from_email: Required. From email.
• from_name: Required. From name.
• reply_email: Required. Reply-to email.
• sender_email: Required. Sender email.
• speed: Required. Campaign speed.
• vmta_id: Required. VMTA id.
• bounce_email_id: Required. Bounce email id.
• url_domain_id: Required. URL domain id.

Sample Request Body Structure

{
"user_id": 123,
"template_id": 456,
"mailing_list_id": 789,
"campaign_name": "May Newsletter",
"begins_at": "2026-05-06 18:00:00",
"segment": "all",
"all_request": {
"subject": "Hello from SMTPProvider",
"html_body": "<h1>Hello</h1>",
"text_body": "Hello",
"from_email": "news@example.com",
"from_name": "Demo Team",
"reply_email": "support@example.com",
"sender_email": "news@example.com",
"speed": 1000,
"vmta_id": 1,
"bounce_email_id": 1,
"url_domain_id": 1
}
}

Response Data Key: campaign

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-campaign-pause

Purpose: Toggles a campaign between paused and resumed states.

Request Fields

• user_id: Required. Authenticated user id.
• campaign_id: Required. Campaign id.

Response Data Key: campaign

Method: GET

Full URL: https://app.smtpprovider.com/api/v1/smtp-campaign-edit?user_id=123&campaign_id=456

Purpose: Returns selected campaign data plus editable sender, template, URL domain, VMTA, bounce email, and speed options.

Query Fields:

• user_id: Required. Authenticated user id.
• campaign_id: Required. Campaign id.

Response Data Keys: campaign, senderDetails, templates, url_domains, vmtas, bounce_email_id, speed

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-campaign-update

Purpose: Updates campaign content and delivery settings.

Request Fields

• user_id: Required. Authenticated user id.
• campaign_id: Required. Campaign id.
• campaign_name: Required. Updated campaign name.
• all_request: Required. Same content and delivery keys used by smtp-campaign-store. begins_at is not required for update.

Sample Request Body Structure

{
"user_id": 123,
"campaign_id": 456,
"campaign_name": "May Newsletter Updated",
"all_request": {
"subject": "Updated Subject",
"html_body": "<h1>Updated HTML</h1>",
"text_body": "Updated plain text",
"from_email": "news@example.com",
"from_name": "Demo Team",
"reply_email": "support@example.com",
"sender_email": "news@example.com",
"speed": 1000,
"vmta_id": 1,
"bounce_email_id": 1,
"url_domain_id": 1
}
}

Sample Success Response

{
    "success": true,
    "data": {
        "campaigns": "update sucessfully"
    }
}

Method: POST

Full URL: https://app.smtpprovider.com/api/v1/smtp-welcome-mail

Purpose: Sends a welcome or subscription email. If subject is provided, html_content is sent directly. Otherwise the default Shopify welcome mail is sent using shop_name.

Request Fields

• from_email: Required. Recipient email address.
• shop_name: Required. Shop name used by the default welcome mail.
• subject: Optional. Custom subject. If provided, html_content is used.
• html_content: Required when subject is provided. Custom HTML email body.

Sample Request with Default Template

{
    "from_email": "owner@example.com",
    "shop_name": "Demo Store"
}

Sample Request with Custom HTML

{
    "from_email": "owner@example.com",
    "shop_name": "Demo Store",
    "subject": "Welcome to SMTPProvider",
    "html_content": "<h1>Welcome</h1>"
}

Sample Success Message: Subscription Mail Sent Successfully

• Store the token securely and send it only in the Authorization header.
• Always use the user.id returned by smtp-token-generate as user_id in protected endpoints.
• POST is recommended for integration consistency.
• DNS verification depends on public DNS propagation and may fail until records are visible globally.