Cosmoner Docs
SDKs

Email

Send transactional email from your code through a project's SMTP credential.

client.email.send() sends a message through one of your project's SMTP credentials over HTTPS, so your code does not need an SMTP connection. It needs an API key with email:write.

Before you can send, the project needs a verified sending domain and a credential on it. The SMTP Setup guide walks through both. The credential's id is what you pass as credentialId.

Send an email

const { data } = await client.email.send({
  credentialId: "cred_...",
  to: ["alice@example.com", "bob@example.com"],
  subject: "Your order has shipped",
  html: "<p>Your order <strong>#1042</strong> is on its way.</p>",
  text: "Your order #1042 is on its way.",
  replyTo: "support@yourdomain.com",
});

console.log(data.messageId);
ParameterTypeRequiredDescription
credentialIdstringYesThe SMTP credential to send through. Its configured address becomes the From header.
tostring or listYesUp to 50 recipients.
subjectstringYes, unless sending a templateSubject line.
htmlstringOne of these, unless sending a templateHTML body.
textstringOne of these, unless sending a templatePlain-text body. Send both for the best deliverability.
templateobjectNoA published template to send instead of subject, html and text. See Send a template.
replyTostring or listNoUp to 5 reply-to addresses.
projectIdstringNoOverrides the client's project.

Python takes the same parameters in snake_case: credential_id, reply_to, project_id.

Send a template

Email templates are not available yet. Until they are, the API refuses a send that carries template with 422 VALIDATION_ERROR.

Name a published email template by its id or alias, and pass values for the variables it declares. The template supplies the subject and both bodies, so leave out subject, html and text: the SDK refuses a call that mixes the two. The key needs email-templates:read as well as email:write.

const { data } = await client.email.send({
  credentialId: "cred_...",
  to: "ada@example.com",
  template: {
    id: "order-shipped",
    variables: { firstName: "Ada", orderNumber: "1042" },
  },
});

console.log(data.messageId, data.template?.version);
FieldTypeRequiredDescription
idstringYesThe template's id or alias.
versionintegerNoA specific version to send. Leave it out to send the published version.
variablesobjectNoValues for the template's variables, checked against what it declares.

Python takes these as template_id, template_version and template_variables. Every recipient of one send gets the same variables.

The response's data.template names the id, alias and version that were sent. A template that does not exist, or has no published version, is refused before anything is sent, and so are variables that do not match its declarations; see Send with a Template for each error.

Things to know

  • A send is not retried on a timeout or a 5xx. The API may have sent the message before it failed to answer, so replaying the request could deliver it twice. Only a 429 is retried automatically. If you retry a send yourself, accept that the recipient may get it twice.
  • There are two limits. Short bursts are capped per minute; going over that gives a 429, which the SDK waits out and retries for you. The project's hourly send limit is different: reaching it is refused with a ValidationError that says so, and it is not retried, because retrying will not help until the hour moves on. See Send Limits.
  • The domain must be verified. Sending through a credential whose domain has not passed its DNS check is refused with a ValidationError.
  • One credential, one sender address. To send from several addresses, create a credential for each.

To find out what happened to a message after it was sent — delivered, bounced, opened — subscribe a webhook to the email.* events.

On this page