This page explains how to send emails using the Console API. Before getting started, make sure to set up a project and familiarize yourself with the Console API.
Endpoint:
POST /api/console/sends
Request:
type Request = SendRequest;This is an SendRequest object, which is used to define the email you want to send.
interface SendRequest {
// The email address of the sender (required)
// the domain of the email address must be verified
from: Address;
// The email address of the recipient (required)
to: Address;
// The subject of the email
subject?: string;
// The body of the email in HTML format
// required if body_text is not provided
body_html?: string;
// The body of the email in plain text format
// required if body_html is not provided
body_text?: string;
// additional headers
headers?: Record<string, string>;
attachments?: Attachment[];
}
type Address = string | {
name?: string;
email: string;
};
type Attachment = {
content: string; // base64 encoded
name?: string;
content_type?: string; // MIME type
};{
// email address with a name
"from": {
"name": "HYVOR",
"email": "[email protected]"
},
// email address without a name
"to": "[email protected]",
"subject": "Welcome to HYVOR",
"body_html": "<h1>Welcome to HYVOR</h1><p>Thank you for signing up!</p>",
"body_text": "Welcome to HYVOR\n\nThank you for signing up!",
"headers": {
"X-Custom-Header": "Custom Value"
},
"attachments": [
{
"content": "SFlWT1IgUm9ja3Mh",
"name": "hello.txt",
"content_type": "text/plain"
}
]
}The HTTP request to send an email may fail due to network issues or other temporary problems. To prevent losing emails, we recommend configuring your application to retry automatically if the API returns a non-2xx status code with incremental backoff.
The recommended retry strategy is to send emails asynchronously and retry up to 3 times with an exponential backoff strategy (e.g., 30s, 2m, 5m). If the request fails after 3 retries, you can log the error and notify your team to investigate the issue.
If your setup sends emails synchronously (ex: within a web request), you can still implement retrying with a smaller timeouts, such as 1s, 2s, and 5s.
When retrying it is possible that your request was already accepted and queued by the API, but
the response was not received by your application due to a network issue. To prevent sending the
same email multiple times, you can use the X-Idempotency-Key header in your request.
This header should contain a unique idempotency key for each email you send.
Some idempotency key examples:
welcome-email-{userId} order-confirmation-{orderId} Idempotency keys are saved for 24 hours. If you retry a request with the same idempotency key before the 24-hour period ends, the API will return the same response as the first request without actually processing it. If the idempotency key is not found, the API will process the request as usual and return a new response.
X-Idempotency-Short-Circuit header is set to true if the response was created
using a previously processed request with the same idempotency key.
Retry-After header value. If you are using an idempotency
key, you can retry with the same key.If the server returns a 5xx status code, idempotency keys are not saved, and retrying the request is recommended. For 4xx status codes, except 429, the idempotency key is saved, and retrying the request will not have any effect unless you change the request and use a new idempotency key.
Send status, as in the Console API Send Object, can be one of the following:
bounced or complained later.See Webhook Send Events for more information on each status.
TODO