SDKs
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: ["[email protected]", "[email protected]"],
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: "[email protected]",
});
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 | Subject line. |
html | string | One of these | HTML body. |
text | string | One of these | Plain-text body. Send both for the best deliverability. |
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.
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.