Email Settings API

Overview

The Email Settings API provides comprehensive management of email configuration for your Stack9 account. This includes sender identities, sending domains, subscription types, suppressions, and email compliance settings. Use these endpoints to configure how emails are sent from your application and manage recipient preferences.

Resource Description

Email settings control the fundamental email sending capabilities of your Stack9 account, including:

Sender Identities: Approved email addresses and display names for sending emails
Sending Domains: Verified domains with proper DNS configuration for email delivery
Subscription Types: Categories of emails that recipients can opt in/out of
Suppressions: Manage email addresses that should not receive emails
Sandbox Mode: Testing configuration to restrict email delivery to whitelisted addresses
Event Webhooks: Real-time notifications for email events

Authentication

All endpoints require API key authentication:

X-API-Key: your-api-key-here

Get Email Settings

Retrieve complete email settings configuration for the account, including sender identities, sending domains, compliance status, and sandbox mode settings.

Endpoint

GET /api/email_settings

Usage

This endpoint returns all email configuration for your account in a single response. Use it to:

Verify sender identity configuration
Check domain verification status
Review subscription types
Inspect sandbox mode settings

Parameters

None

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/email_settings \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json'

Example Response

{
  "version": 2,
  "created_at": "2024-01-15T10:30:00.123Z",
  "updated_at": "2024-03-20T14:45:30.456Z",
  "sender_identities": [
    {
      "from_name": "Marketing Team",
      "from_email_address": "marketing@example.com",
      "reply_to": "support@example.com",
      "company_address": "123 Main St, Suite 400",
      "city": "San Francisco",
      "nickname": "Marketing Default"
    },
    {
      "from_name": "Customer Support",
      "from_email_address": "noreply@example.com",
      "reply_to": "support@example.com",
      "nickname": "Support Notifications"
    }
  ],
  "whitelist_recipient_rules": [
    {
      "email_address": "test@example.com",
      "active": true
    },
    {
      "domain_name": "internal.example.com",
      "active": true
    }
  ],
  "subscription_types": [
    {
      "id": "sub_1234",
      "name": "Marketing Emails",
      "description": "Promotional content and special offers",
      "active": true
    },
    {
      "id": "sub_5678",
      "name": "Product Updates",
      "description": "New features and product announcements",
      "active": true
    }
  ],
  "subscriber_additional_fields": {
    "company": {
      "label": "Company Name",
      "type": "text",
      "order": 1,
      "group": "Professional",
      "field_width_percent": 50
    },
    "phone": {
      "label": "Phone Number",
      "type": "text",
      "order": 2,
      "group": "Contact",
      "field_width_percent": 50
    }
  },
  "sandbox_mode": false,
  "sending_domains": [
    {
      "creation_time": "2024-01-15T10:30:00Z",
      "domain": "example.com",
      "is_default_bounce_domain": true,
      "status": {
        "mx_status": "valid",
        "spf_status": "valid",
        "cname_status": "valid",
        "ownership_verified": true,
        "abuse_at_status": "valid",
        "compliance_status": "valid",
        "verification_mailbox_status": "valid",
        "dkim_status": "valid",
        "postmaster_at_status": "valid"
      }
    }
  ],
  "event_webhooks": [
    {
      "name": "Main Event Webhook",
      "target": "https://api.example.com/webhooks/email",
      "events": ["delivery", "bounce", "complaint", "open", "click"],
      "active": true,
      "last_successful": "2024-03-20T14:30:00Z",
      "last_failure": null
    }
  ]
}

Response Fields

Field	Type	Description
`version`	integer	Version number incremented on each update
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update
`sender_identities`	array	List of configured sender identities
`whitelist_recipient_rules`	array	Email addresses/domains allowed in sandbox mode
`subscription_types`	array	Available subscription categories
`subscriber_additional_fields`	object	Custom fields for subscriber records
`sandbox_mode`	boolean	Whether sandbox mode is active
`sending_domains`	array	Configured and verified sending domains
`event_webhooks`	array	Configured webhooks for email events

Update Email Settings

Update the email settings configuration for your account.

Endpoint

PUT /api/email_settings

Usage

Use this endpoint to:

Add or modify sender identities
Update subscription types
Configure whitelist rules for sandbox mode
Define custom subscriber fields

Parameters

Parameter	Type	Required	Description
`sender_identities`	array	Yes	List of sender identity configurations
`whitelist_recipient_rules`	array	Yes	Sandbox mode whitelist rules
`subscription_types`	array	Yes	Available subscription categories
`subscriber_additional_fields`	object	Yes	Custom fields for subscribers

Example Request

curl -X PUT \
  https://apis.app.stack9.co/api/email_settings \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender_identities": [
      {
        "from_name": "Sales Team",
        "from_email_address": "sales@example.com",
        "reply_to": "sales@example.com",
        "company_address": "123 Main St",
        "city": "New York",
        "nickname": "Sales Outreach"
      }
    ],
    "whitelist_recipient_rules": [
      {
        "email_address": "dev@example.com",
        "active": true
      }
    ],
    "subscription_types": [
      {
        "id": "sub_9012",
        "name": "Weekly Newsletter",
        "description": "Our weekly company newsletter",
        "active": true
      }
    ],
    "subscriber_additional_fields": {
      "department": {
        "label": "Department",
        "type": "text",
        "order": 1
      }
    }
  }'

Example Response

{
  "id": "email_settings_updated"
}

Get Sending Domains

Retrieve the list of configured sending domains for the account.

Endpoint

GET /api/email_settings/sending_domains

Usage

Use this endpoint to:

Check domain verification status
Identify which domains are configured for email sending
Monitor domain compliance status

Parameters

None

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/email_settings/sending_domains \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json'

Example Response

[
  {
    "creation_time": "2024-01-15T10:30:00Z",
    "domain": "example.com",
    "is_default_bounce_domain": true,
    "status": {
      "mx_status": "valid",
      "spf_status": "valid",
      "cname_status": "valid",
      "ownership_verified": true,
      "abuse_at_status": "valid",
      "compliance_status": "valid",
      "verification_mailbox_status": "valid",
      "dkim_status": "valid",
      "postmaster_at_status": "valid"
    }
  },
  {
    "creation_time": "2024-02-01T09:00:00Z",
    "domain": "mail.example.com",
    "is_default_bounce_domain": false,
    "status": {
      "mx_status": "pending",
      "spf_status": "valid",
      "cname_status": "pending",
      "ownership_verified": false,
      "abuse_at_status": "pending",
      "compliance_status": "pending",
      "verification_mailbox_status": "pending",
      "dkim_status": "pending",
      "postmaster_at_status": "pending"
    }
  }
]

Manage Subscription Types

Get All Subscription Types

GET /api/email_settings/subscription_types

Retrieve all subscription types configured for the account.

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/email_settings/subscription_types \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "results": [
    {
      "id": "sub_1234",
      "name": "Marketing Emails",
      "description": "Promotional content and offers",
      "active": true
    },
    {
      "id": "sub_5678",
      "name": "Transactional",
      "description": "Order confirmations and receipts",
      "active": true
    }
  ]
}

Get Subscription Type by ID

GET /api/email_settings/subscription_types/{id}

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Subscription type ID

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/email_settings/subscription_types/sub_1234 \
  -H 'X-API-Key: your-api-key-here'

Manage Sender Identities

Get All Sender Identities

GET /api/email_settings/sender_identities

Retrieve all configured sender identities for the account.

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/email_settings/sender_identities \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "results": [
    {
      "from_name": "Support Team",
      "from_email_address": "support@example.com",
      "reply_to": "support@example.com",
      "company_address": "123 Main St",
      "city": "San Francisco",
      "nickname": "Support"
    }
  ]
}

Delete Sender Identity

DELETE /api/email_settings/sender_identities/{from_email_address}

Remove a sender identity from the account.

Parameters

Parameter	Type	Required	Description
`from_email_address`	string	Yes	Email address of sender identity to delete

Example Request

curl -X DELETE \
  https://apis.app.stack9.co/api/email_settings/sender_identities/old@example.com \
  -H 'X-API-Key: your-api-key-here'

Manage Suppressions

Suppressions prevent emails from being sent to specific recipients.

List Suppressions

GET /api/email_settings/suppressions/list

Retrieve all suppressed email addresses.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 20, max: 100)
`type`	string	No	Filter by suppression type (bounce, complaint, unsubscribe)

Example Request

curl -X GET \
  'https://apis.app.stack9.co/api/email_settings/suppressions/list?page=1&pageSize=50' \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "results": [
    {
      "recipient": "bounced@example.com",
      "type": "bounce",
      "description": "Hard bounce - mailbox does not exist",
      "created_at": "2024-03-15T10:30:00Z"
    },
    {
      "recipient": "unsubscribed@example.com",
      "type": "unsubscribe",
      "description": "User unsubscribed",
      "created_at": "2024-03-10T14:20:00Z"
    }
  ],
  "metadata": {
    "total": 45,
    "page": 1,
    "pageSize": 50
  }
}

Get Suppression by Recipient

GET /api/email_settings/suppressions/list/{recipient}

Check if a specific email address is suppressed.

Parameters

Parameter	Type	Required	Description
`recipient`	string	Yes	Email address to check

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/email_settings/suppressions/list/test@example.com \
  -H 'X-API-Key: your-api-key-here'

Delete Suppression

DELETE /api/email_settings/suppressions/{recipient}

Remove an email address from the suppression list.

Parameters

Parameter	Type	Required	Description
`recipient`	string	Yes	Email address to remove from suppression

Example Request

curl -X DELETE \
  https://apis.app.stack9.co/api/email_settings/suppressions/recovered@example.com \
  -H 'X-API-Key: your-api-key-here'

Error Handling

The Email Settings API returns standard HTTP status codes and error responses:

Common Error Responses

400 Bad Request

{
  "error": {
    "code": "INVALID_SENDER_IDENTITY",
    "message": "Sender email address must match a verified domain",
    "details": {
      "field": "from_email_address",
      "value": "unverified@domain.com"
    }
  }
}

404 Not Found

{
  "error": {
    "code": "SUPPRESSION_NOT_FOUND",
    "message": "No suppression found for recipient",
    "details": {
      "recipient": "unknown@example.com"
    }
  }
}

409 Conflict

{
  "error": {
    "code": "DUPLICATE_SENDER_IDENTITY",
    "message": "Sender identity already exists",
    "details": {
      "from_email_address": "existing@example.com"
    }
  }
}

Best Practices

Domain Verification

Complete DNS Configuration: Ensure all DNS records (SPF, DKIM, CNAME) are properly configured
Monitor Status: Regularly check domain verification status
Default Bounce Domain: Set one verified domain as the default bounce domain

Sender Identities

Use Descriptive Nicknames: Make identities easy to identify in the UI
Complete Address Information: Include full company address for compliance
Separate Reply-To: Use different reply-to addresses for better email management

Subscription Management

Clear Descriptions: Provide clear descriptions for each subscription type
Granular Control: Offer multiple subscription types for user preference
Honor Unsubscribes: Always respect user subscription preferences

Sandbox Mode

Development Testing: Use sandbox mode during development
Whitelist Test Addresses: Add all test email addresses to whitelist
Domain Whitelisting: Use domain whitelisting for team testing

Suppression Management

Regular Monitoring: Review suppression lists regularly
Handle Bounces: Process bounce notifications to maintain list hygiene
Respect Unsubscribes: Never remove unsubscribe suppressions without explicit consent

Rate Limits

Email Settings API endpoints have the following rate limits:

Endpoint	Limit	Window
GET endpoints	100 requests	1 minute
PUT/POST endpoints	20 requests	1 minute
DELETE endpoints	10 requests	1 minute

Webhook Events

Configure webhooks to receive real-time notifications for email events:

Available Events

Event	Description
`delivery`	Email successfully delivered
`bounce`	Email bounced (hard or soft)
`complaint`	Recipient marked as spam
`open`	Email was opened
`click`	Link in email was clicked
`unsubscribe`	Recipient unsubscribed

Webhook Payload Example

{
  "event": "delivery",
  "timestamp": "2024-03-20T15:30:00Z",
  "recipient": "user@example.com",
  "campaign_id": "camp_123",
  "email_id": "email_456",
  "metadata": {
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  }
}

Migration Guide

If migrating from another email service provider:

Export Suppression Lists: Import existing suppressions before sending
Verify Domains: Complete domain verification before migration
Configure Sender Identities: Set up all sender identities in advance
Test in Sandbox: Use sandbox mode to test integration
Update Webhooks: Configure webhooks for event processing
Gradual Migration: Migrate traffic gradually to monitor deliverability

Overview​

Resource Description​

Authentication​

Get Email Settings​

Endpoint​

Usage​

Parameters​

Example Request​

Example Response​

Response Fields​

Update Email Settings​

Endpoint​

Usage​

Parameters​

Example Request​

Example Response​

Get Sending Domains​

Endpoint​

Usage​

Parameters​

Example Request​

Example Response​

Manage Subscription Types​

Get All Subscription Types​

Example Request​

Example Response​

Get Subscription Type by ID​

Parameters​

Example Request​

Manage Sender Identities​

Get All Sender Identities​

Example Request​

Example Response​

Delete Sender Identity​

Parameters​

Example Request​

Manage Suppressions​

List Suppressions​

Query Parameters​

Example Request​

Example Response​

Get Suppression by Recipient​

Parameters​

Example Request​

Delete Suppression​

Parameters​

Example Request​

Error Handling​

Common Error Responses​

400 Bad Request​

404 Not Found​

409 Conflict​

Best Practices​

Domain Verification​

Sender Identities​

Subscription Management​

Sandbox Mode​

Suppression Management​

Rate Limits​

Webhook Events​

Available Events​

Webhook Payload Example​

Migration Guide​

Overview

Resource Description

Authentication

Get Email Settings

Endpoint

Usage

Parameters

Example Request

Example Response

Response Fields

Update Email Settings

Endpoint

Usage

Parameters

Example Request

Example Response

Get Sending Domains

Endpoint

Usage

Parameters

Example Request

Example Response

Manage Subscription Types

Get All Subscription Types

Example Request

Example Response

Get Subscription Type by ID

Parameters

Example Request

Manage Sender Identities

Get All Sender Identities

Example Request

Example Response

Delete Sender Identity

Parameters

Example Request

Manage Suppressions

List Suppressions

Query Parameters

Example Request

Example Response

Get Suppression by Recipient

Parameters

Example Request

Delete Suppression

Parameters

Example Request

Error Handling

Common Error Responses

400 Bad Request

404 Not Found

409 Conflict

Best Practices

Domain Verification

Sender Identities

Subscription Management

Sandbox Mode

Suppression Management

Rate Limits

Webhook Events

Available Events

Webhook Payload Example

Migration Guide