Send one email

Use this when one person should get an email right away. A welcome after signup, a password reset, an order receipt, and a booking confirmation all use this same call.

It sends a template you already saved. It does not create a campaign, so the project does not fill up with one campaign per person.

Before you call

• Save the email as a template in this project. Copy its id from GET /api/v1/templates, or from Email Templates.
• Create an API key that includes the messages:send scope. A key created before this scope existed cannot send until you create a new key and include messages:send.
• Optional: create a list, such as Signups, and copy its id from GET /api/v1/lists. Pass that id as list_id and the person is added to that list. The list has to belong to this project.
• Call this from the brand's server, right after signup or the order succeeds. The key only affects that one project.

What one call does

• Saves the person as a contact. The same email updates the contact you already have.
• Adds them to list_id when you send one. Other people already on that list are not emailed.
• Sends the template to that email only.
• Fills {{first_name}}, {{last_name}}, {{email}}, and {{full_name}} in the subject and the body. A blank first name stays blank unless the template sets a default, such as {{first_name | default: "there"}}.

Welcome email, send once

Set once to true. If this address already received this template, the person is still saved and added to the list, and the email is not sent again.

{
  "email": "ada@example.com",
  "first_name": "Ada",
  "list_id": 12,
  "once": true
}

Put the template id from this project in the URL path.

Receipt or password reset

Leave once out, or set it to false. Each call sends the email again. Leave list_id out when this person should not join a list.

{
  "email": "ada@example.com",
  "first_name": "Ada",
  "once": false
}

People who opted out

An address that already unsubscribed returns HTTP 409 and is not emailed. The code is ALREADY_UNSUBSCRIBED. Pass force_resubscribe true only after they ask to receive email again.

A bounced address is saved and can still be added to the list. The email is not sent. The response has sent false, skipped true, and reason bounced.

Response

• sent true means the email went out. The HTTP status is 201.
• sent false, skipped true, and reason already_sent means once was true and this person already received this template. The HTTP status is 200. They are still on the list.
• sent false, skipped true, and reason bounced means the mailbox was already marked bounced.
• If the mail server rejects the message, the contact is still saved. The HTTP status is 502 and the code is send_failed. Call the same request again to retry. A failed send does not count as already sent.

The message includes an unsubscribe link. If the person uses it, they are removed from every list in this project.