← All API sections

Emails

Send and track transactional emails

7 endpoints
Menu

Endpoints

MethodPathDescription
GET/v1/emailsList emails with pagination and filters
POST/v1/emailsSend a single email
POST/v1/emails/batchSend up to 500 emails in a single request
POST/v1/emails/broadcastSend an email to all active subscribers in a contact list
GET/v1/emails/{id}Get email details with events
POST/v1/emails/{id}/cancel
GET/v1/emails/{id}/linksPer-link click statistics for an email

GET /v1/emails

List emails with pagination and filters

Parameters

NameInTypeRequiredDescription
pagequeryintegerNoPage number (default: 1)
per_pagequeryintegerNoItems per page (default: 25)
statusquerystringNoFilter by status (queued, sent, bounced, failed)
from_datequerystringNoFilter from date (ISO 8601)
to_datequerystringNoFilter to date (ISO 8601)

Responses

StatusDescription
200Paginated list of emails
401Unauthorized

Example

curl -X GET https://api.euromail.dev/v1/emails \
  -H "Authorization: Bearer em_live_..."
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({ apiKey: "em_live_..." });

const result = await euromail.listEmails();
from euromail import EuroMail

client = EuroMail(api_key="em_live_...")

result = client.list_emails()
use euromail::EuroMail;

let client = EuroMail::new("em_live_...");

let result = client.list_emails().await?;
client := euromail.NewClient("em_live_...")

result, err := client.ListEmails(ctx)

POST /v1/emails

Send a single email

Request Body

FieldTypeRequiredDescription
attachmentsAttachmentRequest[]NoFiles to attach.
bccstring[]NoBlind carbon-copy recipients.
ccstring[]NoCarbon-copy recipients.
fromstringYesSender address. Its domain must be one you added and verified in the dashboard; a display name is allowed ("Acme <[email protected]>").
headersanyNoExtra headers to add to the message, as a name-to-value object.
html_bodystring | nullNoHTML body. Send html_body, text_body or both; omit both only when template_alias renders the content.
idempotency_keystring | nullNoOptional idempotency key. If provided, a duplicate send with the same key (per account) returns the original email instead of creating a new one.
metadataanyNoFree-form key-value data stored with the email and returned in webhooks.
reply_tostring | nullNoAddress replies are sent to.
send_atstring | nullNoTime to send the email (ISO 8601). Omit to send immediately.
streamstring | nullNoMessage stream slug. Routes this email through the named stream, enabling separate reputation tracking for transactional vs. marketing email. Defaults to "transactional". The stream must exist for the account.
subjectstring | nullNoSubject line. Required unless template_alias supplies one.
tagsstring[]NoLabels for filtering and analytics.
template_aliasstring | nullNoAlias of a stored template to render instead of html_body and text_body.
template_dataanyNoVariables passed to the template named by template_alias.
text_bodystring | nullNoPlain-text body, used as the text alternative of html_body.
tostring | string[]YesSingle recipient "[email protected]" or several ["[email protected]", "[email protected]"].
trackingboolean | nullNoPer-email tracking override. When false, disables open/click tracking for this email even if the account has tracking enabled. When true, enables tracking even if the account default is off. Omit to use account default.
transactionalboolean | nullNoWhether this is a transactional email (password reset, receipt, notification). When true or omitted, List-Unsubscribe headers are omitted so Gmail routes the message to the Primary inbox instead of Promotions. Set to false for marketing or newsletter emails that need one-click unsubscribe. Only an explicit true reaches a recipient who unsubscribed: omitting the field keeps the unsubscribe in force.

Responses

StatusDescription
202Email accepted for delivery. data is one email when to holds one address, and one email per address when it holds several.
401Unauthorized (code AUTH_MISSING, AUTH_MALFORMED or AUTH_INVALID_KEY)
403The sender domain is not on the account (code SENDER_DOMAIN_NOT_REGISTERED), sending is paused, or a card check is required
422Validation error, a suppressed recipient (code RECIPIENT_SUPPRESSED), or an attachment was refused (code ATTACHMENT_REFUSED)
429Rate limit or quota exceeded
503The attachment scanner could not answer; retry after the Retry-After delay (code ATTACHMENT_SCAN_UNAVAILABLE)

Example

curl -X POST https://api.euromail.dev/v1/emails \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Welcome aboard",
  "html_body": "<h1>Welcome</h1><p>Your account is ready.</p>"
}'
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({ apiKey: "em_live_..." });

const result = await euromail.sendEmail({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome aboard",
  html_body: "<h1>Welcome</h1><p>Your account is ready.</p>"
});
from euromail import EuroMail

client = EuroMail(api_key="em_live_...")

result = client.send_email(
    from_address="[email protected]",
    to="[email protected]",
    subject="Welcome aboard",
    html_body="<h1>Welcome</h1><p>Your account is ready.</p>",
)
use euromail::{EuroMail, SendEmailParams};

let client = EuroMail::new("em_live_...");

let result = client.send_email(
    &SendEmailParams::new("[email protected]", "[email protected]")
        .subject("Welcome aboard")
        .html_body("<h1>Welcome</h1><p>Your account is ready.</p>")
).await?;
client := euromail.NewClient("em_live_...")

result, err := client.SendEmail(ctx, euromail.SendEmailParams{
    From: "[email protected]",
    To: euromail.Recipients("[email protected]"),
    Subject: euromail.String("Welcome aboard"),
    HTMLBody: euromail.String("<h1>Welcome</h1><p>Your account is ready.</p>"),
})

POST /v1/emails/batch

Send up to 500 emails in a single request. Returns an operation_id for tracking, a data array of queued emails, and an errors array for any per-email failures. Partial success is supported. An email refused by a send-rate limit or the new-account allowance is also listed in rate_limited with code RATE_LIMIT_EXCEEDED and retry_after_seconds. When no email was accepted and every refusal is such a limit, the response is 429 with a retry-after header set to the longest wait; the body is the same.

Request Body

FieldTypeRequiredDescription
emailsSendEmailRequest[]YesThe emails to send, each shaped like the body of POST /v1/emails.

Responses

StatusDescription
202Batch accepted for delivery
401Unauthorized
422Validation error, or no email was accepted and not all refusals were rate limits
429Every email was refused by a send-rate limit or the new-account allowance, or the account's request limit was hit. The retry-after header holds the longest wait.

Example

curl -X POST https://api.euromail.dev/v1/emails/batch \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    {
      "from": "[email protected]",
      "to": "[email protected]",
      "subject": "Welcome aboard",
      "html_body": "<h1>Welcome</h1><p>Your account is ready.</p>"
    }
  ]
}'
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({ apiKey: "em_live_..." });

const result = await euromail.sendBatch({
  emails: [
    {
      from: "[email protected]",
      to: "[email protected]",
      subject: "Welcome aboard",
      html_body: "<h1>Welcome</h1><p>Your account is ready.</p>"
    }
  ]
});
from euromail import EuroMail, SendEmailParams

client = EuroMail(api_key="em_live_...")

result = client.send_batch(
    emails=[
        SendEmailParams(
            from_address="[email protected]",
            to="[email protected]",
            subject="Welcome aboard",
            html_body="<h1>Welcome</h1><p>Your account is ready.</p>",
        ),
    ],
)
use euromail::{EuroMail, SendBatchParams, SendEmailParams};

let client = EuroMail::new("em_live_...");

let result = client.send_batch(&SendBatchParams {
    emails: vec![
        SendEmailParams::new("[email protected]", "[email protected]")
            .subject("Welcome aboard")
            .html_body("<h1>Welcome</h1><p>Your account is ready.</p>"),
    ],
}).await?;
client := euromail.NewClient("em_live_...")

result, err := client.SendBatch(ctx, euromail.SendBatchParams{
    Emails: []euromail.SendEmailParams{
        {
            From: "[email protected]",
            To: euromail.Recipients("[email protected]"),
            Subject: euromail.String("Welcome aboard"),
            HTMLBody: euromail.String("<h1>Welcome</h1><p>Your account is ready.</p>"),
        },
    },
})

POST /v1/emails/broadcast

Send an email to all active subscribers in a contact list

Request Body

FieldTypeRequiredDescription
contact_list_idstringYes
from_addressstringYes
headersanyNo
html_bodystring | nullNo
reply_tostring | nullNo
send_atstring | nullNo
subjectstring | nullNo
tagsstring[]No
template_aliasstring | nullNo
template_dataanyNo
text_bodystring | nullNo
trackingboolean | nullNo
transactionalbooleanNoWhether this is a transactional broadcast. Defaults to false because bulk sends are typically marketing emails that need List-Unsubscribe headers for Gmail/Yahoo compliance. Set to true only for operational bulk sends (e.g. account migration notices) where unsubscribe headers are inappropriate.

Responses

StatusDescription
202Broadcast accepted for delivery
401Unauthorized
404Contact list not found
422Validation error

Example

curl -X POST https://api.euromail.dev/v1/emails/broadcast \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "contact_list_id": "3f8b1c52-7a4e-4d0b-9c61-2e5d8a7f4b10",
  "from_address": "[email protected]"
}'
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({ apiKey: "em_live_..." });

const result = await euromail.sendBroadcast({
  contact_list_id: "3f8b1c52-7a4e-4d0b-9c61-2e5d8a7f4b10",
  from_address: "[email protected]"
});
from euromail import EuroMail

client = EuroMail(api_key="em_live_...")

result = client.send_broadcast(
    contact_list_id="3f8b1c52-7a4e-4d0b-9c61-2e5d8a7f4b10",
    from_address="[email protected]",
)
use euromail::{EuroMail, BroadcastParams};

let client = EuroMail::new("em_live_...");

let result = client.send_broadcast(&BroadcastParams {
    contact_list_id: "3f8b1c52-7a4e-4d0b-9c61-2e5d8a7f4b10".into(),
    from_address: "[email protected]".into(),
    ..Default::default()
}).await?;
client := euromail.NewClient("em_live_...")

result, err := client.SendBroadcast(ctx, euromail.BroadcastParams{
    ContactListID: "3f8b1c52-7a4e-4d0b-9c61-2e5d8a7f4b10",
    FromAddress: "[email protected]",
})

GET /v1/emails/{id}

Get email details with events

Parameters

NameInTypeRequiredDescription
idpathstringYesEmail ID

Responses

StatusDescription
200Email details with events
401Unauthorized
404Email not found

Example

curl -X GET https://api.euromail.dev/v1/emails/{id} \
  -H "Authorization: Bearer em_live_..."
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({ apiKey: "em_live_..." });

const result = await euromail.getEmail("id_...");
from euromail import EuroMail

client = EuroMail(api_key="em_live_...")

result = client.get_email("id_...")
use euromail::EuroMail;

let client = EuroMail::new("em_live_...");

let result = client.get_email("id_...").await?;
client := euromail.NewClient("em_live_...")

result, err := client.GetEmail(ctx, "id_...")

POST /v1/emails/{id}/cancel

Parameters

NameInTypeRequiredDescription
idpathstringYesEmail ID

Responses

StatusDescription
200Scheduled email cancelled
401Unauthorized
404Email not found or not in scheduled status

Example

curl -X POST https://api.euromail.dev/v1/emails/{id}/cancel \
  -H "Authorization: Bearer em_live_..."
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({ apiKey: "em_live_..." });

const result = await euromail.cancelEmail("id_...");
from euromail import EuroMail

client = EuroMail(api_key="em_live_...")

result = client.cancel_email("id_...")
use euromail::EuroMail;

let client = EuroMail::new("em_live_...");

let result = client.cancel_email("id_...").await?;
client := euromail.NewClient("em_live_...")

result, err := client.CancelEmail(ctx, "id_...")

Per-link click statistics for an email

Parameters

NameInTypeRequiredDescription
idpathstringYesEmail ID

Responses

StatusDescription
200Per-link click statistics
401Unauthorized
403Forbidden
404Email not found

Example

curl -X GET https://api.euromail.dev/v1/emails/{id}/links \
  -H "Authorization: Bearer em_live_..."
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({ apiKey: "em_live_..." });

const result = await euromail.getEmailDetail("id_...");
from euromail import EuroMail

client = EuroMail(api_key="em_live_...")

result = client.get_email_detail("id_...")
use euromail::EuroMail;

let client = EuroMail::new("em_live_...");

let result = client.get_email_detail("id_...").await?;
client := euromail.NewClient("em_live_...")

result, err := client.GetEmailDetail(ctx, "id_...")