Explore documentation
  1. Welcome to Incidents 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Tag on-call in Slack
    4. Mobile apps ↗
    5. Connecting external calendars
    6. Advanced guide
  4. Incident management
    1. Get started
    2. AI SRE investigations
    3. Post mortems
    4. Metadata & Catalog
    5. Screening alerts
    6. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Incidents API
    1. Getting an API token
    2. Pagination
    3. Monitors
    4. Heartbeats
    5. On-call & incidents
    6. Status pages
    7. Metadata
    8. Integrations
      1. New Relic
      2. Datadog
      3. AWS CloudWatch
      4. Amazon SNS
      5. Microsoft Azure
      6. Google Monitoring
      7. Grafana
      8. Elastic
      9. Prometheus
      10. E-mail
      11. Incoming webhooks
      12. Atlassian Jira
      13. Slack
      14. Outgoing webhooks
      15. Outgoing e‑mails
        1. List outgoing e‑mails GET
        2. Get outgoing e‑mail GET
        3. Create outgoing e‑mail POST
        4. Update outgoing e‑mail PATCH
        5. Remove outgoing e‑mail DELETE
      16. Splunk On-Call
      17. PagerDuty
      18. Catalog
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

List outgoing e-mails

Returns a list of all your outgoing e-mail integrations.

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

Query parameters

team_name
string

Filter outgoing e-mail integrations belonging to a specified team when using a global API token.

page
integer

The page number to return, starting with 1.

per_page
integer

Number of results per page. Defaults to 50, maximum 250.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns a list of existing outgoing e-mail integrations.

Response body

{
  "data": [
    {
      "id": "42",
      "type": "outgoing_email",
      "attributes": {
        "name": "Client distribution list",
        "recipients": [
          {
            "email": "ops@client.com",
            "first_name": "Sam",
            "team": "SRE"
          },
          {
            "email": "noc@client.com"
          }
        ],
        "team_name": "My team",
        "paused": false,
        "notify_alongside_primary_responder": true,
        "on_incident_started": true,
        "on_incident_acknowledged": false,
        "on_incident_resolved": true,
        "on_incident_reopened": true,
        "on_incident_comment": false,
        "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."
          }
        ]
      }
    }
  ],
  "pagination": {
    "first": "https://incidents.betterstack.com/api/v2/outgoing-emails?page=1",
    "last": "https://incidents.betterstack.com/api/v2/outgoing-emails?page=1",
    "prev": null,
    "next": null
  }
}

Response attributes

id
string

The ID of the outgoing e-mail integration.

type
string

Always outgoing_email.

attributes.name
string or null

The name of the outgoing e-mail integration shown in the dashboard.

attributes.recipients
array

The addresses that receive incident e-mails, each with any custom attributes such as first_name at the top level, which templates insert with $RECIPIENT.<key>.

attributes.recipients[].email
string

The recipient's e-mail address.

attributes.team_name
string

The team this integration belongs to.

attributes.paused
boolean

Whether the integration is paused in the dashboard, which stops its e-mails. Read-only.

attributes.notify_alongside_primary_responder
boolean

Whether recipients are notified alongside the primary responder when no escalation policy is configured.

attributes.on_incident_started
boolean

Whether an e-mail is sent when an incident starts.

attributes.on_incident_acknowledged
boolean

Whether an e-mail is sent when an incident is acknowledged.

attributes.on_incident_resolved
boolean

Whether an e-mail is sent when an incident is resolved.

attributes.on_incident_reopened
boolean

Whether an e-mail is sent when an incident is reopened.

attributes.on_incident_comment
boolean

Whether an e-mail is sent when a comment is added to an incident.

attributes.templates
array

The per-event message templates, one per customized incident stage.

attributes.templates[].incident_stage
string

The event the template applies to: started, acknowledged, resolved, reopened, or comment.

attributes.templates[].subject
string or null

The e-mail subject line. Supports variables such as $NAME, $STATUS, and $RECIPIENT.<key>.

attributes.templates[].title
string or null

The e-mail title. Supports the same variables as subject.

attributes.templates[].body
string or null

The e-mail body. Supports the same variables as subject.

pagination.first
string

The URL of the first page. Read more about pagination.

pagination.last
string

The URL of the last page.

pagination.prev
string or null

The URL of the previous page, or null on the first page.

pagination.next
string or null

The URL of the next page, or null on the last page.

Example cURL

Example
curl --request GET \
  --url https://incidents.betterstack.com/api/v2/outgoing-emails \
  --header "Authorization: Bearer $TOKEN"


Previous article

Remove outgoing webhook

Next article

Get outgoing e-mail