← Back to docs

Newsletters

Collect subscribers and send newsletters with EuroMail

Menu

Hosted Signup Forms

EuroMail provides embeddable signup forms for collecting newsletter subscribers. Turn on double_opt_in on the contact list so new subscribers confirm their address before they are added.

Create a signup form for a list via the dashboard or API:

curl -X POST https://api.euromail.dev/v1/signup-forms \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "LIST_ID",
    "title": "Blog Newsletter",
    "redirect_url": "https://yoursite.com/thanks"
  }'

The response includes the hosted form URL and an embed snippet you can drop into any page. See Signup Forms & Double Opt-In.

Contact Lists

Organize subscribers into contact lists. Each list has its own signup form, unsubscribe handling, and sending history.

# Create a list
curl -X POST https://api.euromail.dev/v1/contact-lists \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Updates", "description": "Monthly product updates"}'

Creating a newsletter

A newsletter starts as a draft tied to one contact list. Write it in the dashboard editor, or create it through the API with your own HTML:

curl -X POST https://api.euromail.dev/v1/newsletters \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "LIST_ID",
    "subject": "March Product Update",
    "from_address": "[email protected]",
    "html_body": "<h1>What is new</h1><p>...</p>",
    "text_body": "What is new ...",
    "tags": ["product-update"]
  }'

The call returns 201 Created with the draft in data.

FieldRequiredNotes
list_idYesThe contact list to send to.
subjectYes
from_addressYesAn address on one of your domains.
html_body, text_bodyOne of these, or template_idThe content.
template_idNoA stored template to use for the content.
template_dataNoA JSON object of variables for the template.
reply_toNoWhere replies go.
tagsNoUp to 10 tags, each 1 to 256 characters.

Creating and editing a newsletter needs the emails:send scope. Reading needs emails:read. Sending also needs contacts:manage. See API key scopes.

Personalising with contact data

A newsletter that uses a template (template_id, with the values it needs in template_data) is rendered once per recipient, and each recipient's contact is available as contact:

<p>Hi {{ contact.first_name | default("there") }},</p>
<p>This month's update for {{ contact.email }}.</p>

{{ contact.email }} is the recipient's address, and {{ contact.<field> }} is any field of the metadata stored on the contact. Broadcasts that use a template_alias work the same way. A newsletter with a raw html_body is sent as written and never rendered as a template. For the details, including what happens when a contact lacks a field, see Contact variables in templates.

Managing drafts

# List newsletters (newest first; limit defaults to 20, at most 100)
curl "https://api.euromail.dev/v1/newsletters?limit=20&offset=0" \
  -H "Authorization: Bearer em_live_..."

# Fetch one
curl https://api.euromail.dev/v1/newsletters/{id} \
  -H "Authorization: Bearer em_live_..."

# Change a draft: send only the fields you want to change
curl -X PUT https://api.euromail.dev/v1/newsletters/{id} \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{"subject": "March Product Update (revised)"}'

# Delete a draft
curl -X DELETE https://api.euromail.dev/v1/newsletters/{id} \
  -H "Authorization: Bearer em_live_..."

The list response is { "data": [...], "total": N }. Only drafts can be changed or deleted. Once a newsletter has been sent, an update returns 422 and a delete returns 404. A successful delete returns 204 No Content.

A newsletter's status is draft, then sending once you send it, and sent when every subscriber has been processed. It is failed if the send could not go ahead.

Sending

Sending goes to every active subscriber on the list:

curl -X POST https://api.euromail.dev/v1/newsletters/{id}/send \
  -H "Authorization: Bearer em_live_..."

Before accepting the send, EuroMail checks that the newsletter is still a draft, has content, has a valid from_address, and that the list has at least one active subscriber. If any of these fails you get a 422 that says why, and nothing is sent.

The whole list is counted against your monthly quota when you send. If the quota cannot hold it, the call answers 429 with QUOTA_EXCEEDED and nothing is sent; the newsletter stays a draft. A paid plan whose first invoice is paid can send past its included quota and is billed for the overage.

EuroMail handles unsubscribe links (List-Unsubscribe header), bounce processing, and complaint handling automatically. Subscriber records are stored in Finland; messages are delivered to subscriber mail servers, which may be outside the EU.

When the checks pass, the API answers 202 Accepted and sends in the background:

{
  "data": {
    "operation_id": "7f9c2b1e-...",
    "total_recipients": 1240,
    "message": "Newsletter to 1240 recipients accepted for delivery"
  }
}

The same ID is in the X-Operation-Id response header. Poll it to follow progress:

curl https://api.euromail.dev/v1/operations/{operation_id} \
  -H "Authorization: Bearer em_live_..."

See Tracking long-running operations for what the operation reports.

New accounts. Every newsletter is checked by the content classifier before it goes out. An account sends at once when it has a proven sending history, or when it has settled a payment and is past the new-account period. Any other account's newsletter waits for the classifier's verdict if there is none yet when the send starts. The messages show as queued in the meantime. A clean verdict releases them, a scam verdict cancels them, and if no verdict arrives they are delivered when the hold expires.

Flagged newsletters. If the classifier flags a newsletter as possible phishing, we do not send it and the account goes under review: a person on our team looks at it within 72 hours, and the owner gets an email. While a new account is under review, it can't start a newsletter (403 ACCOUNT_UNDER_REVIEW). Its other mail is accepted and held until the review is done.

Results

Once a newsletter is no longer a draft, fetching it returns a stats object next to data:

{
  "data": { "id": "...", "status": "sent", "...": "..." },
  "stats": {
    "total_recipients": 1240,
    "delivered": 1198,
    "opened": 512,
    "clicked": 87,
    "bounced": 14,
    "unsubscribed": 3
  }
}

These are raw counts, not rates. Divide them yourself if you want percentages, for example opened / delivered. A draft has no stats.

One-off broadcasts

For a single send to a list without keeping a newsletter draft, use POST /v1/emails/broadcast. It takes the content inline and starts at once:

curl -X POST https://api.euromail.dev/v1/emails/broadcast \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_list_id": "LIST_ID",
    "from_address": "[email protected]",
    "subject": "We are moving offices",
    "html_body": "<p>From 1 May we are at ...</p>",
    "text_body": "From 1 May we are at ..."
  }'
FieldRequiredNotes
contact_list_idYesThe list to send to.
from_addressYes
subjectYes, unless template_alias is set
html_body, text_bodyOne of these, or template_alias
template_alias, template_dataNoSend a stored template by its alias.
reply_to, headers, tags, trackingNoAs on a single send.
send_atNoSchedule the broadcast for later.
transactionalNoDefaults to false, so List-Unsubscribe headers are added. Set it to true only for operational notices where an unsubscribe link does not fit.

It needs both the emails:send and contacts:manage scopes. Like a newsletter send, it is refused with 422 when the list has no active subscribers or your allowance cannot cover them. A broadcast returns 202 Accepted with the same operation_id, total_recipients and message fields and the X-Operation-Id header, and you follow it through /v1/operations/{id}.

Send your first email in about 90 seconds

The free tier includes 3,000 emails a month. Email storage and AI processing in Finland, with a DPA on every plan.

Create free account See live delivery data