Explore documentation
  1. Create outgoing e-mail
  2. Get outgoing e-mail
  3. List outgoing e-mails
  4. Remove outgoing e-mail
  5. Response attributes
  6. Update outgoing e-mail

Create outgoing e-mail

Returns either a newly created outgoing e-mail integration, or validation errors. See the outgoing e-mails guide for the dashboard walkthrough.

POST https://incidents.betterstack.com/api/v2/outgoing-emails

Headers

Authorization
required string

Bearer $TOKEN

Content-Type
string

application/json

Body parameters

team_name
string

Required if using a global API token to specify the team which should own the resource.

name
string

The name of the outgoing e-mail integration that you can see in the dashboard.

recipients
required array

The addresses that receive incident e-mails. At least one recipient is required. Each entry is either a plain e-mail string, or an object with an email key plus your own custom attribute keys, which you can insert into templates with $RECIPIENT.<key>.

Plain strings and objects can be mixed
{
  "recipients": [
    "noc@client.com",
    { "email": "ops@client.com", "first_name": "Sam", "team": "SRE" }
  ]
}
on_incident_started
boolean

Whether to send an e-mail when an incident starts. Defaults to true.

on_incident_acknowledged
boolean

Whether to send an e-mail when an incident is acknowledged. Defaults to true.

on_incident_resolved
boolean

Whether to send an e-mail when an incident is resolved. Defaults to true.

on_incident_reopened
boolean

Whether to send an e-mail when an incident is reopened. Defaults to true.

on_incident_comment
boolean

Whether to send an e-mail when a new comment is added to an incident. Defaults to true. At least one of the on_incident_* triggers must be enabled.

notify_alongside_primary_responder
boolean

Whether to notify recipients alongside the primary responder when no escalation policy is configured. Defaults to true.

templates
array

Per-event message templates. Each entry is an object that customizes the e-mail for one incident stage. Leave a field empty to use the default copy for that stage. Insert incident details with variables such as $NAME, $STATUS, $CAUSE, and $INCIDENT_URL, recipient attributes with $RECIPIENT.<key>, and incident metadata with $METADATA.Key or $METADATA_ARRAY. The incidents API documentation lists every available variable.

Each template targets one incident_stage
{
  "templates": [
    {
      "incident_stage": "started",
      "subject": "Incident: $NAME",
      "title": "We're investigating an issue with $NAME",
      "body": "Hi $RECIPIENT.first_name, we detected a problem: $CAUSE. Follow along at $INCIDENT_URL."
    },
    {
      "incident_stage": "resolved",
      "subject": "Resolved: $NAME"
    }
  ]
}

incident_stage is one of started, acknowledged, resolved, reopened, comment. The array is declarative: stages you include are created or updated, stages you omit from the array are removed, and omitting the templates parameter entirely leaves existing templates untouched.

201

Returns the newly created outgoing e-mail integration

Response body

{
  "data": {
    "id": "42",
    "type": "outgoing_email",
    "attributes": {
      "name": "Client distribution list",
      "recipients": [
        {
          "email": "noc@client.com"
        },
        {
          "email": "ops@client.com",
          "first_name": "Sam",
          "team": "SRE"
        }
      ],
      "team_name": "My team",
      "paused": false,
      "notify_alongside_primary_responder": true,
      "on_incident_started": true,
      "on_incident_acknowledged": true,
      "on_incident_resolved": true,
      "on_incident_reopened": true,
      "on_incident_comment": true,
      "templates": [
        {
          "incident_stage": "started",
          "subject": "Incident: $NAME",
          "title": "We're investigating an issue with $NAME",
          "body": "Hi $RECIPIENT.first_name, we detected a problem: $CAUSE. Follow along at $INCIDENT_URL."
        }
      ]
    }
  }
}
403

Your plan doesn't include outgoing e-mail integrations

Response body

{
  "errors": "Can't add an outgoing e-mail integration. Upgrade your account to send incident notifications to external e-mail addresses."
}
422

Returns validation errors, for example no recipients or no trigger enabled

Response body

{
  "errors": {
    "base": [
      "Please add at least one e-mail address"
    ]
  }
}

Example cURL

Example
curl -X "POST" "https://incidents.betterstack.com/api/v2/outgoing-emails" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "Client distribution list",
  "recipients": [
    "noc@client.com",
    { "email": "ops@client.com", "first_name": "Sam" }
  ],
  "on_incident_started": true,
  "on_incident_resolved": true,
  "templates": [
    { "incident_stage": "started", "subject": "Incident: $NAME" }
  ]
}'


Next article

Get outgoing e-mail