The Sender Identities API allows you to create and manage sender identities for Marketing Campaigns.

The nickname, from.email, address, city, and country parameters are required when creating and updating sender identities.

Create a Sender Identity [POST]

This endpoint allows you to create a sender identity.

You may create up to 100 unique sender identities.

Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the from.email.

Request

1
POST https://api.sendgrid.com/v3/senders HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "nickname": "My Sender ID",
  "from": {
    "email": "from@example.com",
    "name": "Example INC"
  },
  "reply_to": {
    "email": "example@example.com",
    "name": "Example INC"
  },
  "address": "123 Elm St.",
  "address_2": "Apt. 456",
  "city": "Denver",
  "state": "Colorado",
  "zip": "80202",
  "country": "United States"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": 1,
  "nickname": "My Sender ID",
  "from": {
    "email": "from@example.com",
    "name": "Example INC"
  },
  "reply_to": {
    "email": "example@example.com",
    "name": "Example INC"
  },
  "address": "123 Elm St.",
  "address_2": "Apt. 456",
  "city": "Denver",
  "state": "Colorado",
  "zip": "80202",
  "country": "United States",
  "verified": true,
  "updated_at": 1449872165,
  "created_at": 1449872165,
  "locked": false
}

Retrieve All Sender Identities [GET]

This endpoint allows you to retrieve a list of all of your sender identities.

Request

1
GET https://api.sendgrid.com/v3/senders HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "result": [
    {
      "id": 1,
      "nickname": "My Sender ID",
      "from": {
        "email": "from@example.com",
        "name": "Example INC"
      },
      "reply_to": {
        "email": "example@example.com",
        "name": "Example INC"
      },
      "address": "123 Elm St.",
      "address_2": "Apt. 456",
      "city": "Denver",
      "state": "Colorado",
      "zip": "80202",
      "country": "United States",
      "verified": true,
      "updated_at": 1449872165,
      "created_at": 1449872165,
      "locked": false
    }
  ]
}

Update a Sender Identity [PATCH]

Updates to from.email require re-verification. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the from.email.

Partial updates are allowed, but fields that are marked as “required” in the POST (create) endpoint must not be nil if that field is included in the PATCH request.

Request

1
PATCH https://api.sendgrid.com/v3/senders/{sender_id} HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "nickname": "My Sender ID",
  "from": {
    "email": "from@example.com",
    "name": "Example INC"
  },
  "reply_to": {
    "email": "example@example.com",
    "name": "Example INC"
  },
  "address": "123 Elm St.",
  "address_2": "Apt. 456",
  "city": "Denver",
  "state": "Colorado",
  "zip": "80202",
  "country": "United States"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": 1,
  "nickname": "My Sender ID",
  "from": {
    "email": "from@example.com",
    "name": "Example INC"
  },
  "reply_to": {
    "email": "example@example.com",
    "name": "Example INC"
  },
  "address": "123 Elm St.",
  "address_2": "Apt. 456",
  "city": "Denver",
  "state": "Colorado",
  "zip": "80202",
  "country": "United States",
  "verified": true,
  "updated_at": 1449872165,
  "created_at": 1449872165,
  "locked": false
}

Delete a Sender Identity [DELETE]

This endpoint allows you to delete one of your sender identities.

Request

1
DELETE https://api.sendgrid.com/v3/senders/{sender_id} HTTP/1.1

Response

1
HTTP/1.1 204

Resend Sender Identity Verification [POST]

This endpoint allows you to resend the sender identity verification email.

Request

1
POST https://api.sendgrid.com/v3/senders/{sender_id}/resend_verification HTTP/1.1

Response

1
HTTP/1.1 204

Retrieve a Specific Sender Identity [GET]

This endoint allows you to retrieve a specific sender identity.

Request

1
GET https://api.sendgrid.com/v3/senders/{sender_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": 1,
  "nickname": "My Sender ID",
  "from": {
    "email": "from@example.com",
    "name": "Example INC"
  },
  "reply_to": {
    "email": "example@example.com",
    "name": "Example INC"
  },
  "address": "123 Elm St.",
  "address_2": "Apt. 456",
  "city": "Denver",
  "state": "Colorado",
  "zip": "80202",
  "country": "United States",
  "verified": true,
  "updated_at": 1449872165,
  "created_at": 1449872165,
  "locked": false
}