SMTP Setup

Prerequisites

• A project with a payment method
• 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.

Every email is billed, so the project needs a payment method before a domain can go active. If it has none, verification answers 402 and the control panel asks for a card, then retries. See Email Pricing.

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.

To keep an email's wording and layout in the control panel rather than in your code, store it as an email template and send it by its alias through the API. The credential still decides the sender.

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 is on an email plan — Pay as you go, or a plan with emails included — which sets the per-email rate and the daily and hourly limits. You can check your plan, usage and limits:

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

To change plan (owners and admins only, as it changes what the project is billed):

PUT /v1/projects/:projectId/email/plan

The monthly cap is the most a month can send. On a plan it starts at the included emails, and raising it allows the emails beyond them, billed at the plan's rate. Like the plan, only owners and admins can change it:

PUT /v1/projects/:projectId/email/monthly-cap

If you need a higher hourly 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.

Sending Reputation

Mailbox providers judge every sender by how much of its mail bounces and how much recipients mark as spam. Cosmoner tracks both rates for your project over a trailing window, and shows them, with the thresholds your project is held to, on the project's Email page:

• Bounces count mail sent to addresses that do not exist. An address that has bounced is never sent to again, and those blocked sends do not count against you.
• Spam complaints count mail a recipient reported as spam.

Rates are only judged once your project has sent enough mail in the window for them to mean something. When either rate reaches its warning threshold, the project's biller gets an email and a notification. When either reaches its suspension threshold, email sending for the project is suspended: SMTP refuses new messages with a permanent 550 error, and the API answers 403 EMAIL_SENDING_SUSPENDED. A suspension does not lift on its own — open a support ticket and tell us what was sent and what you have changed.

To read the same figures programmatically:

GET /v1/projects/:projectId/email/reputation

To keep both rates low, only send to people who asked for your mail, remove addresses that bounce, confirm new sign-ups before mailing them, and include a working unsubscribe link in anything that is not a direct response to the recipient. Webhooks deliver every bounce and complaint as it happens, so you can act on them automatically.

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