SMTP Setup

Prerequisites

• A project with an active subscription
• A domain added to your project (purchased or migrated)

1. Enable Email for Your Domain

Enable email sending on a domain in your project:

POST /v1/projects/:projectId/email

{
  "domainId": "your-domain-id"
}

This generates DKIM keys and returns the DNS records you need to add.

2. Add DNS Records

The response includes three DNS records to add at your DNS provider:

Add all three records. DNS propagation can take up to 48 hours, but usually completes within minutes.

3. Verify DNS

Once your DNS records are in place, trigger verification:

POST /v1/projects/:projectId/email/:emailDomainId/verify

If the records resolve correctly, your domain status changes to ACTIVE and you can start sending email.

4. Create SMTP Credentials

Create credentials for your application to authenticate with:

POST /v1/projects/:projectId/email/:emailDomainId/credentials

{
  "label": "Transactional",
  "fromAddress": "[email protected]"
}

The response includes a password that is shown once and cannot be retrieved again. Store it securely. The fromAddress must belong to the verified domain. It is also the only sender address that this credential can use.

{
  "success": true,
  "data": {
    "id": "...",
    "label": "Transactional",
    "fromAddress": "[email protected]",
    "smtpUsername": "smtp_abc123",
    "smtpPassword": "generated-password"
  }
}

5. Send Email

Use the credentials with any SMTP client or library. Example configuration:

The relay replaces the message's From header with the credential's configured address. Create a separate credential for each sender address you need.

Node.js Example (Nodemailer)

const transporter = nodemailer.createTransport({
  host: "smtp.cosmoner.com",
  port: 587,
  secure: false,
  auth: {
    user: "smtp_abc123",
    pass: "your-credential-password",
  },
});

await transporter.sendMail({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Hello",
  text: "Hello from Cosmoner!",
});

Send Limits

Each project has an hourly send limit. You can check your current usage and limit:

GET /v1/projects/:projectId/email/limits

If you need a higher limit, request an increase:

POST /v1/projects/:projectId/email/limit-increase

Limit increase requests are reviewed by the Cosmoner team. You'll receive a notification when your request is approved or rejected.

Managing Credentials

List Credentials

Credentials are included when listing email domains:

GET /v1/projects/:projectId/email

Passwords are never returned after creation.

Delete a Credential

DELETE /v1/projects/:projectId/email/:emailDomainId/credentials/:credentialId