Dartmouth API Developer Portal

Email Addresses API

Returns information about email addresses. This API returns information from multiple source systems. Currently only addresses from Advancement are in the API. Other source systems can be added by request with a TDX ticket at API Enhancements.

Rating

Required Scopes

The email addresses API provides one API for getting information from multiple source systems. Each system can require a particular scope, or one scope will be available to read all possible email addresses. Currently only addresses from the Advancement system available. Authorization for consuming this data will be handled by the Advancement IT team.

Future enhancement scopes might be:

urn:dartmouth:email_addresses:read.sis
urn:dartmouth:email_addresses:read.hrs
urn:dartmouth:email_addresses:read.idm
urn:dartmouth:email_addresses:read.all

Request

GET /api/email_addresses/{id}

Required Headers

Authorization: Bearer {jwt}

Notes on usage

The Email Addresses API is designed to support multiple source systems with different formats and source information. Each source system will have a separate authorization process to recieve a scope allowing access to that systems email address data.

A typical use case is retrieving email addresses for one netid. That is accomplished with the following query:

/api/email_addresses?netid=d22970n

Each email address resource is assigned a surrogate resource id. To access a single email address use the follwing GET call:

/api/email_addresses/{id}

Another use case might be getting all email addresses for a particular source system such as:

/api/email_addresses?data_source=adv

The top level attributes for all email address objects will be the same. For source system specific attributes, the object "data_source_data" will contain attributes pertinent for that particular system and will not have the same attribute names.

The Email Addresses API is availble for filtering and paged result sets consistent with the syntax specified in the introduction section covering filtering and paging.

Returns

Top Level Payload Attribute Descriptions

Detailed descriptions of "data_source_data" for "adv" data_source email addresses

Advance email types

Sample Request

https://api.dartmouth.edu/api/email_addresses?netid=d22970n

Sample Return

[
    {
        "id": "601177f19948a0a6209256dc",
        "netid": "d22970n",
        "email_address": "david.a.bibeau@dartmouth.edu",
        "data_source": "adv",
        "is_primary": false,
        "data_source_data": {
            "type": "Dartmouth Email",
            "is_preferred_ind": false,
            "is_for_vitalyst": false,
            "forwards_to_email_address": null
        },
        "cache_date": "2021-05-17T00:00:23Z"
    },
    {
        "id": "601177f19948a0a6209256dd",
        "netid": "d22970n",
        "email_address": "david.a.bibeau@dartmouth.edu",
        "data_source": "adv",
        "is_primary": false,
        "data_source_data": {
            "type": "Preferred Email",
            "is_preferred_ind": true,
            "is_for_vitalyst": false,
            "forwards_to_email_address": null
        },
        "cache_date": "2021-05-17T00:00:23Z"
    }
]