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);| Parameter | Type | Required | Description |
|---|---|---|---|
credentialId | string | Yes | The SMTP credential to send through. Its configured address becomes the From header. |
to | string or list | Yes | Up to 50 recipients. |
subject | string | Yes, unless sending a template | Subject line. |
html | string | One of these, unless sending a template | HTML body. |
text | string | One of these, unless sending a template | Plain-text body. Send both for the best deliverability. |
template | object | No | A published template to send instead of subject, html and text. See Send a template. |
replyTo | string or list | No | Up to 5 reply-to addresses. |
projectId | string | No | Overrides 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);| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The template's id or alias. |
version | integer | No | A specific version to send. Leave it out to send the published version. |
variables | object | No | Values 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
429is 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 aValidationErrorthat 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.