# Create outgoing e-mail

Returns either a newly created outgoing e-mail integration, or validation errors. See the [outgoing e-mails guide](https://betterstack.com/docs/uptime/integrations/integrating-with-better-uptime/outgoing-emails/) for the dashboard walkthrough.

[endpoint]
base_url = "https://incidents.betterstack.com"
path = "/api/v2/outgoing-emails"
method = "POST"

[[body_param]]
name = "team_name"
description = "Required if using a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) to specify the team which should own the resource."
required = false
type = "string"

[[body_param]]
name = "name"
description = "The name of the outgoing e-mail integration that you can see in the dashboard."
required = false
type = "string"

[[body_param]]
name = "recipients"
description = '''
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>`.
<br/><br/>

```json
[label Plain strings and objects can be mixed]
{
  "recipients": [
    "noc@client.com",
    { "email": "ops@client.com", "first_name": "Sam", "team": "SRE" }
  ]
}
```
'''
required = true
type = "array"

[[body_param]]
name = "on_incident_started"
description = "Whether to send an e-mail when an incident starts. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_acknowledged"
description = "Whether to send an e-mail when an incident is acknowledged. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_resolved"
description = "Whether to send an e-mail when an incident is resolved. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_reopened"
description = "Whether to send an e-mail when an incident is reopened. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_comment"
description = "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."
required = false
type = "boolean"

[[body_param]]
name = "notify_alongside_primary_responder"
description = "Whether to notify recipients alongside the primary responder when no escalation policy is configured. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "templates"
description = '''
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](https://betterstack.com/docs/uptime/api/incidents/) lists every available variable.
<br/><br/>

```json
[label 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.
'''
required = false
type = "array"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = false
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''Returns the newly created outgoing e-mail integration'''
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."
        }
      ]
    }
  }
}'''

[[response]]
status = 403
description = '''Your plan doesn't include outgoing e-mail integrations'''
body = '''{
  "errors": "Can't add an outgoing e-mail integration. Upgrade your account to send incident notifications to external e-mail addresses."
}'''

[[response]]
status = 422
description = '''Returns validation errors, for example no recipients or no trigger enabled'''
body = '''{
  "errors": {
    "base": [
      "Please add at least one e-mail address"
    ]
  }
}'''

[/responses]

#### Example cURL

```shell
[label 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" }
  ]
}'
```

[info]
#### Looking for the details of a specific parameter?
Explore [the list of all outgoing e-mail integration API parameters](https://betterstack.com/docs/uptime/api/outgoing-email-integrations-response-params/).
[/info]