useSend

https://docs.usesend.com/
Admin
useSend is an open-source alternative to email service providers like Resend, Sendgrid, Mailgun, and...
Tokens:36,982
Snippets:239
Trust Score:6.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install the useSend Go SDK

Source: https://docs.usesend.com/get-started/go

Use the go get command to add the SDK to your project dependencies.

```bash
go get github.com/usesend/usesend-go
```

--------------------------------

### Start the dashboard with Docker

Source: https://docs.usesend.com/get-started/local

Command to initiate the dashboard service when using the recommended Docker setup.

```bash
pnpm d
```

--------------------------------

### Install UseSend SDK

Source: https://docs.usesend.com/get-started/python

Install the package using pip.

```bash
pip install usesend
```

--------------------------------

### Start development server

Source: https://docs.usesend.com/get-started/local

Command to launch the development environment.

```bash
pnpm dev
```

--------------------------------

### Install useSend SDK

Source: https://docs.usesend.com/get-started/nodejs

Commands to install the SDK using various package managers.

```bash
npm install usesend-js
```

```bash
yarn add usesend-js
```

```bash
pnpm add usesend-js
```

```bash
bun add usesend-js
```

--------------------------------

### Install project dependencies

Source: https://docs.usesend.com/get-started/local

Enable corepack and install dependencies using pnpm.

```bash
corepack enable
```

```bash
pnpm install
```

--------------------------------

### Initialize environment configuration

Source: https://docs.usesend.com/get-started/local

Copy the example environment file to the active .env file.

```bash
 cp .env.example .env
```

--------------------------------

### Install dependencies

Source: https://docs.usesend.com/guides/use-with-react-email

Install the required packages for useSend and React Email rendering.

```sh
npm install usesend-js @react-email/render
```

```sh
yarn add usesend-js @react-email/render
```

```sh
pnpm add usesend-js @react-email/render
```

```sh
bun add usesend-js @react-email/render
```

--------------------------------

### Run documentation server

Source: https://docs.usesend.com/get-started/local

Starts the local development server for the documentation using pnpm.

```bash
pnpm dev:docs
```

--------------------------------

### Start SMTP Proxy Server

Source: https://docs.usesend.com/self-hosting/overview

Command to initialize and run the SMTP proxy container in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Run standalone useSend container

Source: https://docs.usesend.com/get-started/set-up-docker

Starts the application container with required environment variables for database, Redis, AWS, and authentication services.

```bash
docker run -d \
  -p 3000:3000 \
  -e NEXTAUTH_URL="<your-nextauth-url>" \
  -e NEXTAUTH_SECRET="<your-nextauth-secret>" \
  -e DATABASE_URL="<your-next-private-database-url>" \
  -e REDIS_URL="<your-next-private-redis-url>" \
  -e AWS_ACCESS_KEY_ID="<your-next-private-aws-access-key-id>" \
  -e AWS_SECRET_ACCESS_KEY="<your-next-private-aws-secret-access-key>" \
  -e AWS_DEFAULT_REGION="<your-next-private-aws-region>" \
  -e GITHUB_ID="<your-next-private-github-id>" \
  -e GITHUB_SECRET="<your-next-private-github-secret>" \
  usesend/usesend
```

--------------------------------

### Start production containers with Docker Compose

Source: https://docs.usesend.com/get-started/set-up-docker

Executes the Docker Compose configuration to launch the application and its dependencies in detached mode.

```bash
docker-compose --env-file ./.env up -d
```

--------------------------------

### Define contact properties structure

Source: https://docs.usesend.com/guides/campaign-personalization

Example JSON structure for a contact with custom properties.

```json
{
  "email": "jane@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "properties": {
    "company": "Acme",
    "plan": "Pro",
    "registrationCode": "WELCOME-2026"
  }
}
```

--------------------------------

### OpenAPI Specification for Get Domain

Source: https://docs.usesend.com/api-reference/domains/get-domain

Defines the GET /v1/domains/{id} endpoint, including path parameters and the structure of the returned domain object.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: useSend API
servers:
  - url: https://app.usesend.com/api
security: []
paths:
  /v1/domains/{id}:
    get:
      parameters:
        - schema:
            type: number
            nullable: true
            example: 1
          required: false
          name: id
          in: path
      responses:
        '200':
          description: Retrieve the domain
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: number
                    description: The ID of the domain
                    example: 1
                  name:
                    type: string
                    description: The name of the domain
                    example: example.com
                  teamId:
                    type: number
                    description: The ID of the team
                    example: 1
                  status:
                    type: string
                    enum:
                      - NOT_STARTED
                      - PENDING
                      - SUCCESS
                      - FAILED
                      - TEMPORARY_FAILURE
                  region:
                    type: string
                    default: us-east-1
                  clickTracking:
                    type: boolean
                    default: false
                  openTracking:
                    type: boolean
                    default: false
                  publicKey:
                    type: string
                  dkimStatus:
                    type: string
                    nullable: true
                  spfDetails:
                    type: string
                    nullable: true
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                  dmarcAdded:
                    type: boolean
                    default: false
                  isVerifying:
                    type: boolean
                    default: false
                  errorMessage:
                    type: string
                    nullable: true
                  subdomain:
                    type: string
                    nullable: true
                  verificationError:
                    type: string
                    nullable: true
                  lastCheckedTime:
                    type: string
                    nullable: true
                  dnsRecords:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - MX
                            - TXT
                          description: DNS record type
                          example: TXT
                        name:
                          type: string
                          description: DNS record name
                          example: mail
                        value:
                          type: string
                          description: DNS record value
                          example: v=spf1 include:amazonses.com ~all
                        ttl:
                          type: string
                          description: DNS record TTL
                          example: Auto
                        priority:
                          type: string
                          nullable: true
                          description: DNS record priority
                          example: '10'
                        status:
                          type: string
                          enum:
                            - NOT_STARTED
                            - PENDING
                            - SUCCESS
                            - FAILED
                            - TEMPORARY_FAILURE
                        recommended:
                          type: boolean
                          description: Whether the record is recommended
                      required:
                        - type
                        - name
                        - value
                        - ttl
                        - status
                required:
                  - id
                  - name
                  - teamId
                  - status
                  - publicKey
                  - createdAt
                  - updatedAt
                  - dnsRecords
```

--------------------------------

### GET /v1/domains

Source: https://docs.usesend.com/api-reference/domains/list-domains

Retrieve a list of all domains accessible by the provided API key.

```APIDOC
## GET /v1/domains

### Description
Retrieve domains accessible by the API key.

### Method
GET

### Endpoint
/v1/domains

### Response
#### Success Response (200)
- **id** (number) - The ID of the domain
- **name** (string) - The name of the domain
- **teamId** (number) - The ID of the team
- **status** (string) - The status of the domain
- **region** (string) - The region of the domain
- **clickTracking** (boolean) - Whether click tracking is enabled
- **openTracking** (boolean) - Whether open tracking is enabled
- **publicKey** (string) - The public key of the domain
- **dkimStatus** (string) - The DKIM status
- **spfDetails** (string) - The SPF details
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Last update timestamp
- **dmarcAdded** (boolean) - Whether DMARC is added
- **isVerifying** (boolean) - Whether the domain is currently verifying
- **errorMessage** (string) - Error message if any
- **subdomain** (string) - The subdomain
- **verificationError** (string) - Verification error message
- **lastCheckedTime** (string) - Last checked timestamp
- **dnsRecords** (array) - List of DNS records associated with the domain

#### Response Example
[
  {
    "id": 1,
    "name": "example.com",
    "teamId": 1,
    "status": "SUCCESS",
    "publicKey": "pk_test_123",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z",
    "dnsRecords": [
      {
        "type": "TXT",
        "name": "mail",
        "value": "v=spf1 include:amazonses.com ~all",
        "ttl": "Auto",
        "status": "SUCCESS",
        "recommended": true
      }
    ]
  }
]
```

--------------------------------

### OpenAPI specification for listing contact books

Source: https://docs.usesend.com/api-reference/contacts/list-contact-books

Defines the GET /v1/contactBooks endpoint and the structure of the returned contact book objects.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: useSend API
servers:
  - url: https://app.usesend.com/api
security: []
paths:
  /v1/contactBooks:
    get:
      responses:
        '200':
          description: Retrieve contact books accessible by the API key
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the contact book
                      example: clx1234567890
                    name:
                      type: string
                      description: The name of the contact book
                      example: Newsletter Subscribers
                    teamId:
                      type: number
                      description: The ID of the team
                      example: 1
                    properties:
                      type: object
                      additionalProperties:
                        type: string
                      description: Custom properties for the contact book
                      example:
                        customField1: value1
                    variables:
                      type: array
                      items:
                        type: string
                      description: >-
                        Allowed personalization variables for contacts in this
                        book
                      example:
                        - registrationCode
                        - company
                    emoji:
                      type: string
                      description: The emoji associated with the contact book
                      example: 📙
                    doubleOptInEnabled:
                      type: boolean
                      description: Whether double opt-in is enabled for new contacts
                      example: true
                    doubleOptInFrom:
                      type: string
                      nullable: true
                      description: >-
                        From address used for double opt-in emails (must use a
                        verified domain)
                      example: Newsletter <hello@example.com>
                    doubleOptInSubject:
                      type: string
                      nullable: true
                      description: Subject line used for double opt-in confirmation email
                      example: Please confirm your subscription
                    doubleOptInContent:
                      type: string
                      nullable: true
                      description: >-
                        Email editor JSON content used for double opt-in
                        confirmation
                    createdAt:
                      type: string
                      description: The creation timestamp
                    updatedAt:
                      type: string
                      description: The last update timestamp
                    _count:
                      type: object
                      properties:
                        contacts:
                          type: number
                          description: The number of contacts in the contact book
                      required:
                        - contacts
                  required:
                    - id
                    - name
                    - teamId
                    - properties
                    - variables
                    - emoji
                    - createdAt
                    - updatedAt
```

--------------------------------

### OpenAPI Specification for List Emails

Source: https://docs.usesend.com/api-reference/emails/list-emails

Defines the GET /v1/emails endpoint, including query parameters for pagination, date filtering, and domain identification.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: useSend API
servers:
  - url: https://app.usesend.com/api
security: []
paths:
  /v1/emails:
    get:
      parameters:
        - schema:
            type: string
            default: '1'
            example: '1'
          required: false
          name: page
          in: query
        - schema:
            type: string
            default: '50'
            example: '50'
          required: false
          name: limit
          in: query
        - schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
          required: false
          name: startDate
          in: query
        - schema:
            type: string
            format: date-time
            example: '2024-01-31T23:59:59Z'
          required: false
          name: endDate
          in: query
        - schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
            example: '123'
          required: false
          name: domainId
          in: query
      responses:
        '200':
          description: Retrieve a list of emails
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        to:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                        replyTo:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                            - nullable: true
                        cc:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                            - nullable: true
                        bcc:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                            - nullable: true
                        from:
                          type: string
                        subject:
                          type: string
                        html:
                          type: string
                          nullable: true
                        text:
                          type: string
                          nullable: true
                        createdAt:
                          type: string
                        updatedAt:
                          type: string
                        latestStatus:
                          type: string
                          nullable: true
                          enum:
                            - SCHEDULED
                            - QUEUED
                            - SENT
                            - DELIVERY_DELAYED
                            - BOUNCED
                            - REJECTED
                            - RENDERING_FAILURE
                            - DELIVERED
                            - OPENED
                            - CLICKED
                            - COMPLAINED
                            - FAILED
                            - CANCELLED
                            - SUPPRESSED
                        scheduledAt:
                          type: string
                          nullable: true
                          format: date-time
                        domainId:
                          type: number
                          nullable: true
                      required:
                        - id
                        - to
                        - from
                        - subject
                        - html
                        - text
                        - createdAt
                        - updatedAt
                        - latestStatus
                        - scheduledAt
                        - domainId
                  count:
                    type: number
                required:
                  - data
                  - count
```

--------------------------------

### OpenAPI Specification for GET /v1/campaigns

Source: https://docs.usesend.com/api-reference/campaigns/get-campaigns

Defines the endpoint parameters for pagination, status filtering, and search, along with the expected JSON response structure.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: useSend API
servers:
  - url: https://app.usesend.com/api
security: []
paths:
  /v1/campaigns:
    get:
      parameters:
        - schema:
            type: string
            description: 'Page number for pagination (default: 1)'
            example: '1'
          required: false
          name: page
          in: query
        - schema:
            type: string
            enum:
              - DRAFT
              - SCHEDULED
              - RUNNING
              - PAUSED
              - SENT
            description: Filter campaigns by status
            example: DRAFT
          required: false
          name: status
          in: query
        - schema:
            type: string
            description: Search campaigns by name or subject
            example: newsletter
          required: false
          name: search
          in: query
      responses:
        '200':
          description: Get list of campaigns
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        from:
                          type: string
                        subject:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                        status:
                          type: string
                        scheduledAt:
                          type: string
                          nullable: true
                          format: date-time
                        total:
                          type: integer
                        sent:
                          type: integer
                        delivered:
                          type: integer
                        unsubscribed:
                          type: integer
                      required:
                        - id
                        - name
                        - from
                        - subject
                        - createdAt
                        - updatedAt
                        - status
                        - scheduledAt
                        - total
                        - sent
                        - delivered
                        - unsubscribed
                  totalPage:
                    type: integer
                required:
                  - campaigns
                  - totalPage
```

--------------------------------

### OpenAPI Specification for Get Contact

Source: https://docs.usesend.com/api-reference/contacts/get-contact

Defines the endpoint path, required path parameters, and the expected JSON response structure for retrieving a contact.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: useSend API
servers:
  - url: https://app.usesend.com/api
security: []
paths:
  /v1/contactBooks/{contactBookId}/contacts/{contactId}:
    get:
      parameters:
        - schema:
            type: string
            example: cuiwqdj74rygf74
          required: true
          name: contactBookId
          in: path
        - schema:
            type: string
            example: cuiwqdj74rygf74
          required: true
          name: contactId
          in: path
      responses:
        '200':
          description: Retrieve the contact
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  firstName:
                    type: string
                    nullable: true
                  lastName:
                    type: string
                    nullable: true
                  email:
                    type: string
                  subscribed:
                    type: boolean
                    default: true
                  properties:
                    type: object
                    additionalProperties:
                      type: string
                  contactBookId:
                    type: string
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                required:
                  - id
                  - email
                  - properties
                  - contactBookId
                  - createdAt
                  - updatedAt
```

--------------------------------

### Get Contact Book OpenAPI Specification

Source: https://docs.usesend.com/api-reference/contacts/get-contact-book

Defines the GET endpoint for retrieving contact book details, including path parameters and response schemas.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: useSend API
servers:
  - url: https://app.usesend.com/api
security: []
paths:
  /v1/contactBooks/{contactBookId}:
    get:
      parameters:
        - schema:
            type: string
            example: clx1234567890
          required: true
          name: contactBookId
          in: path
      responses:
        '200':
          description: Retrieve the contact book
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the contact book
                    example: clx1234567890
                  name:
                    type: string
                    description: The name of the contact book
                    example: Newsletter Subscribers
                  teamId:
                    type: number
                    description: The ID of the team
                    example: 1
                  properties:
                    type: object
                    additionalProperties:
                      type: string
                    description: Custom properties for the contact book
                    example:
                      customField1: value1
                  variables:
                    type: array
                    items:
                      type: string
                    description: >-
                      Allowed personalization variables for contacts in this
                      book
                    example:
                      - registrationCode
                      - company
                  emoji:
                    type: string
                    description: The emoji associated with the contact book
                    example: 📙
                  doubleOptInEnabled:
                    type: boolean
                    description: Whether double opt-in is enabled for new contacts
                    example: true
                  doubleOptInFrom:
                    type: string
                    nullable: true
                    description: >-
                      From address used for double opt-in emails (must use a
                      verified domain)
                    example: Newsletter <hello@example.com>
                  doubleOptInSubject:
                    type: string
                    nullable: true
                    description: Subject line used for double opt-in confirmation email
                    example: Please confirm your subscription
                  doubleOptInContent:
                    type: string
                    nullable: true
                    description: >-
                      Email editor JSON content used for double opt-in
                      confirmation
                  createdAt:
                    type: string
                    description: The creation timestamp
                  updatedAt:
                    type: string
                    description: The last update timestamp
                  _count:
                    type: object
                    properties:
                      contacts:
                        type: number
                        description: The number of contacts in the contact book
                    required:
                      - contacts
                required:
                  - id
                  - name
                  - teamId
                  - properties
                  - variables
                  - emoji
                  - createdAt
                  - updatedAt
        '403':
          description: Forbidden - API key doesn't have access to this contact book
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '404':
          description: Contact book not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
```

--------------------------------

### Initialize the useSend Client

Source: https://docs.usesend.com/get-started/go

Create a new client instance using your API key. The client can also be initialized with a custom base URL for self-hosted instances.

```go
package main

import (
    "context"
    "log"

    usesend "github.com/usesend/usesend-go"
)

func main() {
    client, err := usesend.NewClient("us_12345")
    if err != nil {
        log.Fatal(err)
    }
}
```

```go
client, err := usesend.NewClient(
    "us_12345",
    usesend.WithBaseURL("https://app.usesend.com"),
)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Initialize useSend SDK

Source: https://docs.usesend.com/get-started/nodejs

Initialize the SDK with an API key, optionally providing a base URL for self-hosted instances.

```javascript
import { UseSend } from "usesend-js";

const usesend = new UseSend("us_12345");
```

```javascript
const usesend = new UseSend("us_12345", "https://app.usesend.com");
```

--------------------------------

### GET /v1/contactBooks

Source: https://docs.usesend.com/api-reference/contacts/list-contact-books

Retrieve a list of contact books accessible by the API key.

```APIDOC
## GET /v1/contactBooks

### Description
Retrieve contact books accessible by the API key.

### Method
GET

### Endpoint
https://app.usesend.com/api/v1/contactBooks

### Response
#### Success Response (200)
- **id** (string) - The ID of the contact book
- **name** (string) - The name of the contact book
- **teamId** (number) - The ID of the team
- **properties** (object) - Custom properties for the contact book
- **variables** (array) - Allowed personalization variables for contacts in this book
- **emoji** (string) - The emoji associated with the contact book
- **doubleOptInEnabled** (boolean) - Whether double opt-in is enabled for new contacts
- **doubleOptInFrom** (string) - From address used for double opt-in emails
- **doubleOptInSubject** (string) - Subject line used for double opt-in confirmation email
- **doubleOptInContent** (string) - Email editor JSON content used for double opt-in confirmation
- **createdAt** (string) - The creation timestamp
- **updatedAt** (string) - The last update timestamp
- **_count** (object) - Contains the number of contacts in the contact book

#### Response Example
[
  {
    "id": "clx1234567890",
    "name": "Newsletter Subscribers",
    "teamId": 1,
    "properties": {
      "customField1": "value1"
    },
    "variables": ["registrationCode", "company"],
    "emoji": "📙",
    "doubleOptInEnabled": true,
    "doubleOptInFrom": "Newsletter <hello@example.com>",
    "doubleOptInSubject": "Please confirm your subscription",
    "doubleOptInContent": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "_count": {
      "contacts": 100
    }
  }
]
```

--------------------------------

### GET /v1/campaigns/{campaignId}

Source: https://docs.usesend.com/api-reference/campaigns/get-campaign

Retrieves the full details of a specific campaign by its ID.

```APIDOC
## GET /v1/campaigns/{campaignId}

### Description
Retrieves the details of a specific campaign identified by the provided campaignId.

### Method
GET

### Endpoint
https://app.usesend.com/api/v1/campaigns/{campaignId}

### Parameters
#### Path Parameters
- **campaignId** (string) - Required - The unique identifier of the campaign (e.g., cmp_123).

### Response
#### Success Response (200)
- **id** (string) - Campaign ID
- **name** (string) - Campaign name
- **from** (string) - Sender information
- **subject** (string) - Email subject line
- **previewText** (string) - Preview text
- **contactBookId** (string) - Associated contact book ID
- **html** (string) - HTML content
- **content** (string) - Plain text content
- **status** (string) - Current status of the campaign
- **scheduledAt** (string) - Scheduled date and time
- **batchSize** (integer) - Size of the batch
- **batchWindowMinutes** (integer) - Batch window in minutes
- **total** (integer) - Total recipients
- **sent** (integer) - Number of emails sent
- **delivered** (integer) - Number of emails delivered
- **opened** (integer) - Number of opens
- **clicked** (integer) - Number of clicks
- **unsubscribed** (integer) - Number of unsubscribes
- **bounced** (integer) - Number of bounces
- **hardBounced** (integer) - Number of hard bounces
- **complained** (integer) - Number of complaints
- **replyTo** (array) - List of reply-to addresses
- **cc** (array) - List of CC addresses
- **bcc** (array) - List of BCC addresses
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Last update timestamp
```

--------------------------------

### Initialize UseSend Client

Source: https://docs.usesend.com/get-started/python

Initialize the client with an API key, optionally specifying a custom base URL for self-hosted instances.

```python
from usesend import UseSend, types


# Option A: pass values directly (helpful in scripts/tests)
client = UseSend("us_xxx")

# Option B: custom base URL (self-hosted)
client = UseSend("us_xxx", url="https://your-domain.example")
```

--------------------------------

### GET /v1/contactBooks/{contactBookId}

Source: https://docs.usesend.com/api-reference/contacts/get-contact-book

Retrieves the details of a specific contact book using its ID.

```APIDOC
## GET /v1/contactBooks/{contactBookId}

### Description
Retrieve the details of a specific contact book by its unique identifier.

### Method
GET

### Endpoint
/v1/contactBooks/{contactBookId}

### Parameters
#### Path Parameters
- **contactBookId** (string) - Required - The ID of the contact book to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The ID of the contact book
- **name** (string) - The name of the contact book
- **teamId** (number) - The ID of the team
- **properties** (object) - Custom properties for the contact book
- **variables** (array) - Allowed personalization variables for contacts in this book
- **emoji** (string) - The emoji associated with the contact book
- **doubleOptInEnabled** (boolean) - Whether double opt-in is enabled for new contacts
- **doubleOptInFrom** (string) - From address used for double opt-in emails
- **doubleOptInSubject** (string) - Subject line used for double opt-in confirmation email
- **doubleOptInContent** (string) - Email editor JSON content used for double opt-in confirmation
- **createdAt** (string) - The creation timestamp
- **updatedAt** (string) - The last update timestamp
- **_count** (object) - Contains the number of contacts in the contact book

#### Response Example
{
  "id": "clx1234567890",
  "name": "Newsletter Subscribers",
  "teamId": 1,
  "properties": {
    "customField1": "value1"
  },
  "variables": ["registrationCode", "company"],
  "emoji": "📙",
  "doubleOptInEnabled": true,
  "doubleOptInFrom": "Newsletter <hello@example.com>",
  "doubleOptInSubject": "Please confirm your subscription",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "_count": {
    "contacts": 100
  }
}
```

--------------------------------

### Create Next.js environment symlink

Source: https://docs.usesend.com/get-started/local

Link the root .env file to the web application directory.

```bash
ln -s ../../.env apps/web/.env
```

--------------------------------

### Configure Database and Redis

Source: https://docs.usesend.com/self-hosting/overview

Define the connection strings for the Postgres database and Redis queue.

```env
DATABASE_URL="postgres://<username>:<password>@<host>:<port>/<database-name>"
REDIS_URL="redis://<username>:<password>@<host>:<port>"
```

--------------------------------

### Run database migrations

Source: https://docs.usesend.com/get-started/local

Command to apply schema changes to the local database.

```bash
pnpm db:migrate-dev
```

--------------------------------

### GET /v1/analytics/reputation-metrics

Source: https://docs.usesend.com/api-reference/analytics/reputation-metrics

Retrieves reputation metrics data, optionally filtered by a specific domain ID.

```APIDOC
## GET /v1/analytics/reputation-metrics

### Description
Retrieve reputation metrics data such as delivered counts, bounce rates, and complaint rates.

### Method
GET

### Endpoint
/v1/analytics/reputation-metrics

### Parameters
#### Query Parameters
- **domainId** (string) - Optional - Filter by domain ID

### Response
#### Success Response (200)
- **delivered** (integer) - Number of delivered emails
- **hardBounced** (integer) - Number of hard bounced emails
- **complained** (integer) - Number of complaints
- **bounceRate** (number) - Calculated bounce rate
- **complaintRate** (number) - Calculated complaint rate

#### Response Example
{
  "delivered": 1000,
  "hardBounced": 5,
  "complained": 2,
  "bounceRate": 0.005,
  "complaintRate": 0.002
}
```

--------------------------------

### Test Webhook Payload

Source: https://docs.usesend.com/guides/webhooks

Example JSON payload structure for a webhook.test event sent from the dashboard.

```json
{
  "test": true,
  "webhookId": "wh_abc123",
  "sentAt": "2024-01-15T10:30:00.000Z"
}
```

--------------------------------

### OpenAPI Specification for List Domains

Source: https://docs.usesend.com/api-reference/domains/list-domains

Defines the GET /v1/domains endpoint and the structure of the returned domain objects.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: useSend API
servers:
  - url: https://app.usesend.com/api
security: []
paths:
  /v1/domains:
    get:
      responses:
        '200':
          description: Retrieve domains accessible by the API key
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      description: The ID of the domain
                      example: 1
                    name:
                      type: string
                      description: The name of the domain
                      example: example.com
                    teamId:
                      type: number
                      description: The ID of the team
                      example: 1
                    status:
                      type: string
                      enum:
                        - NOT_STARTED
                        - PENDING
                        - SUCCESS
                        - FAILED
                        - TEMPORARY_FAILURE
                    region:
                      type: string
                      default: us-east-1
                    clickTracking:
                      type: boolean
                      default: false
                    openTracking:
                      type: boolean
                      default: false
                    publicKey:
                      type: string
                    dkimStatus:
                      type: string
                      nullable: true
                    spfDetails:
                      type: string
                      nullable: true
                    createdAt:
                      type: string
                    updatedAt:
                      type: string
                    dmarcAdded:
                      type: boolean
                      default: false
                    isVerifying:
                      type: boolean
                      default: false
                    errorMessage:
                      type: string
                      nullable: true
                    subdomain:
                      type: string
                      nullable: true
                    verificationError:
                      type: string
                      nullable: true
                    lastCheckedTime:
                      type: string
                      nullable: true
                    dnsRecords:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - MX
                              - TXT
                            description: DNS record type
                            example: TXT
                          name:
                            type: string
                            description: DNS record name
                            example: mail
                          value:
                            type: string
                            description: DNS record value
                            example: v=spf1 include:amazonses.com ~all
                          ttl:
                            type: string
                            description: DNS record TTL
                            example: Auto
                          priority:
                            type: string
                            nullable: true
                            description: DNS record priority
                            example: '10'
                          status:
                            type: string
                            enum:
                              - NOT_STARTED
                              - PENDING
                              - SUCCESS
                              - FAILED
                              - TEMPORARY_FAILURE
                          recommended:
                            type: boolean
                            description: Whether the record is recommended
                        required:
                          - type
                          - name
                          - value
                          - ttl
                          - status
                  required:
                    - id
                    - name
                    - teamId
                    - status
                    - publicKey
                    - createdAt
                    - updatedAt
                    - dnsRecords
```

--------------------------------

### View Project Structure

Source: https://docs.usesend.com/get-started/local

Displays the directory layout of the useSend monorepo.

```text
apps
├── docs
├── marketing
├── web
packages
├── eslint-config
├── sdk
├── tailwind-config
├── typescript-config
├── ui
```

--------------------------------

### Create a contact book via API

Source: https://docs.usesend.com/guides/campaign-personalization

Register custom variables for a contact book using the API.

```bash
curl -X POST https://app.usesend.com/api/v1/contactBooks \
  -H "Authorization: Bearer us_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customers",
    "variables": ["company", "plan", "registrationCode"]
  }'
```

--------------------------------

### GET /v1/contactBooks/{contactBookId}/contacts/{contactId}

Source: https://docs.usesend.com/api-reference/contacts/get-contact

Retrieves the details of a specific contact within a given contact book.

```APIDOC
## GET /v1/contactBooks/{contactBookId}/contacts/{contactId}

### Description
Retrieve the details of a specific contact by its ID within a specified contact book.

### Method
GET

### Endpoint
/v1/contactBooks/{contactBookId}/contacts/{contactId}

### Parameters
#### Path Parameters
- **contactBookId** (string) - Required - The unique identifier of the contact book.
- **contactId** (string) - Required - The unique identifier of the contact.

### Response
#### Success Response (200)
- **id** (string) - The contact ID.
- **firstName** (string) - The first name of the contact.
- **lastName** (string) - The last name of the contact.
- **email** (string) - The email address of the contact.
- **subscribed** (boolean) - Subscription status.
- **properties** (object) - Additional contact properties.
- **contactBookId** (string) - The ID of the contact book.
- **createdAt** (string) - Timestamp of creation.
- **updatedAt** (string) - Timestamp of last update.
```

--------------------------------

### Configure database environment variables

Source: https://docs.usesend.com/get-started/local

Required environment variables for connecting to PostgreSQL and Redis instances.

```bash
DATABASE_URL=""
REDIS_URL=""
```

--------------------------------

### GET /v1/campaigns

Source: https://docs.usesend.com/api-reference/campaigns/get-campaigns

Retrieves a list of campaigns based on optional query parameters for pagination, status filtering, and search.

```APIDOC
## GET /v1/campaigns

### Description
Retrieves a list of campaigns. Supports pagination, status filtering, and keyword search.

### Method
GET

### Endpoint
https://app.usesend.com/api/v1/campaigns

### Parameters
#### Query Parameters
- **page** (string) - Optional - Page number for pagination (default: 1)
- **status** (string) - Optional - Filter campaigns by status (DRAFT, SCHEDULED, RUNNING, PAUSED, SENT)
- **search** (string) - Optional - Search campaigns by name or subject

### Response
#### Success Response (200)
- **campaigns** (array) - List of campaign objects
- **totalPage** (integer) - Total number of pages available
```

--------------------------------

### Create a campaign with variables via API

Source: https://docs.usesend.com/guides/campaign-personalization

Include variables in the campaign subject and HTML body.

```bash
curl -X POST https://app.usesend.com/api/v1/campaigns \
  -H "Authorization: Bearer us_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome campaign",
    "from": "Acme <hello@acme.com>",
    "subject": "Welcome to {{company}}",
    "contactBookId": "{contactBookId}",
    "html": "<p>Hi {{firstName,fallback=there}}, your plan is {{plan}}.</p>"
  }'
```

--------------------------------

### GET /v1/emails

Source: https://docs.usesend.com/api-reference/emails/list-emails

Retrieves a list of emails based on optional query parameters for pagination, date filtering, and domain association.

```APIDOC
## GET /v1/emails

### Description
Retrieve a list of emails sent through the platform. Supports pagination and filtering by date range and domain.

### Method
GET

### Endpoint
/v1/emails

### Parameters
#### Query Parameters
- **page** (string) - Optional - Page number (default: '1')
- **limit** (string) - Optional - Number of items per page (default: '50')
- **startDate** (string) - Optional - Start date for filtering (format: date-time)
- **endDate** (string) - Optional - End date for filtering (format: date-time)
- **domainId** (string/array) - Optional - Filter by one or more domain IDs

### Response
#### Success Response (200)
- **data** (array) - List of email objects
- **count** (number) - Total number of emails found
```

--------------------------------

### Create a contact with properties via API

Source: https://docs.usesend.com/guides/campaign-personalization

Assign values to contact properties during creation.

```bash
curl -X POST https://app.usesend.com/api/v1/contactBooks/{contactBookId}/contacts \
  -H "Authorization: Bearer us_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "properties": {
      "company": "Acme",
      "plan": "Pro",
      "registrationCode": "WELCOME-2026"
    }
  }'
```

--------------------------------

### Clone Repository

Source: https://docs.usesend.com/get-started/local

Command to clone the forked useSend repository to a local environment.

```bash
git clone https://github.com/your-username/usesend.git
```

--------------------------------

### GET /v1/domains/{id}

Source: https://docs.usesend.com/api-reference/domains/get-domain

Retrieves the details of a specific domain, including its status, tracking settings, and required DNS records.

```APIDOC
## GET /v1/domains/{id}

### Description
Retrieve the details of a specific domain by its unique identifier.

### Method
GET

### Endpoint
https://app.usesend.com/api/v1/domains/{id}

### Parameters
#### Path Parameters
- **id** (number) - Optional - The ID of the domain to retrieve.

### Response
#### Success Response (200)
- **id** (number) - The ID of the domain
- **name** (string) - The name of the domain
- **teamId** (number) - The ID of the team
- **status** (string) - The status of the domain (NOT_STARTED, PENDING, SUCCESS, FAILED, TEMPORARY_FAILURE)
- **region** (string) - The AWS region
- **clickTracking** (boolean) - Whether click tracking is enabled
- **openTracking** (boolean) - Whether open tracking is enabled
- **publicKey** (string) - The public key for the domain
- **dkimStatus** (string) - DKIM status
- **spfDetails** (string) - SPF details
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Last update timestamp
- **dmarcAdded** (boolean) - Whether DMARC is added
- **isVerifying** (boolean) - Whether the domain is currently verifying
- **errorMessage** (string) - Error message if applicable
- **subdomain** (string) - Subdomain name
- **verificationError** (string) - Verification error details
- **lastCheckedTime** (string) - Last check timestamp
- **dnsRecords** (array) - List of DNS records required for the domain

#### Response Example
{
  "id": 1,
  "name": "example.com",
  "teamId": 1,
  "status": "SUCCESS",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail",
      "value": "v=spf1 include:amazonses.com ~all",
      "ttl": "Auto",
      "status": "SUCCESS",
      "recommended": true
    }
  ]
}
```

--------------------------------

### Configure GitHub app credentials

Source: https://docs.usesend.com/self-hosting/railway

Environment variables for GitHub OAuth authentication.

```env
GITHUB_ID="<your-github-client-id>"
GITHUB_SECRET="<your-github-client-secret>"
```

--------------------------------

### Configure GitHub OAuth URLs

Source: https://docs.usesend.com/get-started/local

Required callback and homepage URLs for GitHub App configuration.

```text
http://localhost:3000/login
```

```text
http://localhost:3000/api/auth/callback/github
```

--------------------------------

### Expose local service with Cloudflare Tunnel

Source: https://docs.usesend.com/get-started/local

Command to generate a public URL for the local dashboard to handle GitHub login callbacks.

```bash
cloudflared tunnel --url http://localhost:3000
```

--------------------------------

### GET /v1/emails/{emailId}

Source: https://docs.usesend.com/api-reference/emails/get-email

Retrieves the details of a specific email by its ID, including recipient information, content, and a history of email events.

```APIDOC
## GET /v1/emails/{emailId}

### Description
Retrieves the details of a specific email by its ID, including recipient information, content, and a history of email events.

### Method
GET

### Endpoint
/v1/emails/{emailId}

### Parameters
#### Path Parameters
- **emailId** (string) - Required - The unique identifier of the email.

### Response
#### Success Response (200)
- **id** (string) - Email ID
- **teamId** (number) - Team ID
- **to** (string|array) - Recipient(s)
- **replyTo** (string|array) - Reply-to address(es)
- **cc** (string|array) - CC address(es)
- **bcc** (string|array) - BCC address(es)
- **from** (string) - Sender address
- **subject** (string) - Email subject
- **html** (string) - HTML content
- **text** (string) - Plain text content
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Last update timestamp
- **emailEvents** (array) - List of events associated with the email
```
Tokens:
Raw