About Sender Details

Developer Preview
APIs in Developer Preview are subject to change and are not intended for use in production.
Send us your suggestions for improving this API. Your feedback is valuable to us.

 

With the Sender Details API you can manage senders for your email campaigns. Sender details consist of a name and an email address, where the email address must be verified through the Sender Emails API beforehand.

You can have multiple senders per site. Using multiple senders allows your letters to come from addresses associated with specific parts of your business. For example, you could have one automated email from bookings@website.com and another from sales@website.com.

With the Sender Details API you can:

Before you begin

It's important to note the following:

  • The first sender you create is automatically marked as the default.
  • Currently, there's a limitation when publishing an email campaign with the Campaign API. The API automatically publishes campaigns from the default sender only. Therefore, whenever you want to publish a different campaign, appropriate sender must be set as the default.
  • If you didn't create any senders, your email campaigns are sent from a domain provided by Wix.
  • You can't delete a default sender. To delete it, you must first create a new sender, mark it as the default, and only then delete the original sender.
  • To add additional senders, you must have Core or Advanced Email Marketing plans.
  • You can't have multiple senders with the same name and email address. If you want to use the same email for multiple senders, the names must be different.

Use cases and flows

Terminology

  • Sender: A combination of a verified email address and a name used to represent the source of an email campaign.
  • Campaign: A single, organized effort to send marketing emails to a list of recipients.
  • Verified Email: An email address that has passed the verification process with the Sender Emails API, allowing it to be used in campaigns.
Did this help?

Sender Details: Sample Use Cases and Flows

This article presents possible use cases and corresponding sample flows that your app can support. It provides a useful starting point as you plan your app's implementation.

Publish an email campaign from a new sender

This use case demonstrates how to send an email campaign from a new sender. For example, if your business now accepts bookings and you want to start a new email campaign, you'll need to send it from a different sender, such as Yoga Bookings: [bookings@yogawithpuppies.com].

Notes:

  • Currently, there's a limitation when publishing an email campaign with the Campaign API. The API automatically publishes campaigns only from the default sender. For this use case to work, you need to set the new sender as the default.
  • This flow assumes that the site owner already created an email campaign.

To publish a campaign from a new sender:

  1. Create and verify the new email address using the Sender Email API.
  2. Call Create Sender Details passing the verified email address into the fromEmailAddress field. Also, enter the sender's name into the fromName field. Save the value of id field for later use.
  3. Call Mark Sender Details as Default and pass the saved ID.
  4. Call Publish Campaign to send out the campaign. The campaign will automatically use the new sender details.
Did this help?

Sender Details Object


Properties
idstringRead-onlyformat GUID

Sender details ID.


createdDatestringRead-onlyformat date-time

Date and time when the sender details were created.


updatedDatestringRead-onlyformat date-time

Date and time when the sender details were updated.


fromNamestringminLength 1maxLength 100

Sender name. This name appears in the email as "from:" name.


fromEmailAddressstringformat EMAILminLength 6maxLength 254

Sender email address. Recipients can also reply to this email address.


defaultbooleanRead-only

Whether the sender is default.


extendedFieldsExtendedFields

Extensions allowing users to save custom data related to the sender details.

SenderDetails
JSON
{ "senderDetails": { "id": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-01T00:00:00.000Z", "fromName": "John Doe", "fromEmailAddress": "john.doe@example.com", "default": true } }
Did this help?

GET

Get Sender Details


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves sender details by ID.

Endpoint
GET
https://www.wixapis.com/sender-details/v1/sender-details/{senderDetailsId}

Path Params
senderDetailsIdstringRequired

Sender details ID.

Response Object
senderDetailsSenderDetails

The requested sender details.

Get Sender Details Example 1
Request
cURL
curl 'https://www.wixapis.com/sender-details/v1/sender-details/3dcaeca5-2b09-441c-86ab-808d85061511' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "senderDetails": { "id": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-01T00:00:00.000Z", "fromName": "John Doe", "fromEmailAddress": "john.doe@example.com", "default": true } }
Did this help?

DELETE

Delete Sender Details


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes a sender.

Note: You can't delete a default sender.

Endpoint
DELETE
https://www.wixapis.com/sender-details/v1/sender-details/{senderDetailsId}

Path Params
senderDetailsIdstringRequired

ID of the sender to delete.

Response Object
Returns an empty object.
Delete Sender Details Example 1
Request
cURL
curl -X DELETE 'https://www.wixapis.com/sender-details/v1/sender-details/a6351a69-f4cb-411c-9853-26634468b03d' \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Errors
428Failed Precondition

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Event TriggersThis method triggers the following events:
Did this help?

GET

Get Default Sender Details


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves default sender details.

Endpoint
GET
https://www.wixapis.com/sender-details/v1/sender-details/default

Request
This endpoint does not take any parameters.
Response Object
senderDetailsSenderDetails

Default sender details.

Get Default Sender Details Example 1
Request
cURL
curl 'https://www.wixapis.com/sender-details/v1/sender-details/default' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "senderDetails": { "id": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-01T00:00:00.000Z", "fromName": "John Doe", "fromEmailAddress": "john.doe@example.com", "default": true } }
Errors
404Not Found

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?

GET

List Sender Details


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of sender details.

Endpoint
GET
https://www.wixapis.com/sender-details/v1/sender-details

Query Params
paging.limitintegerminimum 0maximum 100format int32

Number of items to load.


paging.cursorstringmaxLength 1000

Pointer to the next or previous page in the list of results. You can get the relevant cursor token from the pagingMetadata object in the previous call's response. Not relevant for the first request.

Response Object
pagingMetadataPagingMetadata

Paging metadata.


senderDetailsArray <SenderDetails>maxItems 100

List of sender details.

List Sender Details Example 1
Request
cURL
curl 'https://www.wixapis.com/sender-details/v1/sender-details' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "pagingMetadata": { "count": 2, "cursors": {}, "hasNext": false }, "senderDetails": [ { "id": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-01T00:00:00.000Z", "fromName": "John Doe", "fromEmailAddress": "john.doe@example.com", "default": true }, { "id": "a6351a69-f4cb-411c-9853-26634468b03d", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-01T00:00:00.000Z", "fromName": "Jane Doe", "fromEmailAddress": "jane.doe@example.com", "default": false } ] }
Did this help?

POST

Create Sender Details


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a sender.

Endpoint
POST
https://www.wixapis.com/sender-details/v1/sender-details

Body Params
senderDetailsSenderDetailsRequired

Sender details to create.

Response Object
senderDetailsSenderDetails

The created sender details.

Create Sender Details Example 1
Request
cURL
curl -X POST 'https://www.wixapis.com/sender-details/v1/sender-details' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "senderDetails": { "fromName": "John Doe", "fromEmailAddress": "john.doe@example.com", } }'
Response
JSON
{ "senderDetails": { "id": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-01T00:00:00.000Z", "fromName": "John Doe", "fromEmailAddress": "john.doe@example.com", "default": true } }
Errors
409Already Exists

There is 1 error with this status code:

428Failed Precondition

There are 2 errors with this status code:

See the entire list and learn more about Wix errors.

Event TriggersThis method triggers the following events:
Did this help?

PATCH

Update Sender Details


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates a sender.

Endpoint
PATCH
https://www.wixapis.com/sender-details/v1/sender-details/{senderDetails.id}

Path Params
senderDetails.idstringRequired

Sender details ID.

Body Params
senderDetailsSenderDetailsRequired

Sender details to update.

Response Object
senderDetailsSenderDetails

The updated sender details.

Update Sender Details Example 1
Request
cURL
curl -X PATCH 'https://www.wixapis.com/sender-details/v1/sender-details/3dcaeca5-2b09-441c-86ab-808d85061511' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "senderDetails": { "fromName": "Johnny Doe", "fromEmailAddress": "john.doe@example.com" } }'
Response
JSON
{ "senderDetails": { "id": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-02T00:00:00.000Z", "fromName": "Johnny Doe", "fromEmailAddress": "john.doe@example.com", "default": true } }
Errors
409Already Exists

There is 1 error with this status code:

428Failed Precondition

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Event TriggersThis method triggers the following events:
Did this help?

POST

Mark Sender Details As Default


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Marks a sender as default.

Endpoint
POST
https://www.wixapis.com/sender-details/v1/sender-details/{senderDetailsId}/mark-as-default

Path Params
senderDetailsIdstringRequired

ID of the sender to mark as default.

Response Object
Returns an empty object.
Mark Sender Details As Default Example 1
Request
cURL
curl -X POST 'https://www.wixapis.com/sender-details/v1/sender-details/a6351a69-f4cb-411c-9853-26634468b03d/mark-as-default' \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

Sender Details Created


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a sender is created.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.promote.v1.sender_details.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.promote.v1.sender_details_created", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

SenderDetailsCreated
JSON
{ "id": "9c47296f-349a-4154-828a-dd9ae68ebaba", "entityFqdn": "wix.promote.v1.sender_details", "slug": "created", "entityId": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdEvent": { "entity": { "id": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-01T00:00:00.000Z", "fromName": "John Doe", "fromEmailAddress": "john.doe@example.com", "default": true } }, "eventTime": "2024-01-01T00:00:00.000000000Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "1" }
Did this help?

Sender Details Deleted


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a sender is deleted.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.promote.v1.sender_details.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.promote.v1.sender_details_deleted", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

SenderDetailsDeleted
JSON
{ "id": "f072b4a7-6f70-4ffc-9faf-bc79ec21175b", "entityFqdn": "wix.promote.v1.sender_details", "slug": "deleted", "entityId": "3dcaeca5-2b09-441c-86ab-808d85061511", "deletedEvent": { "movedToTrash": true }, "eventTime": "2024-01-01T00:00:00.000000000Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "15" }
Did this help?

Sender Details Updated


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.promote.v1.sender_details.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.promote.v1.sender_details_updated", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

SenderDetailsUpdated
JSON
{ "id": "cd46f8e2-32ea-4d62-9534-88cd6dc17dca", "entityFqdn": "wix.promote.v1.sender_details", "slug": "updated", "entityId": "3dcaeca5-2b09-441c-86ab-808d85061511", "updatedEvent": { "currentEntity": { "id": "3dcaeca5-2b09-441c-86ab-808d85061511", "createdDate": "2024-01-01T00:00:00.000Z", "updatedDate": "2024-01-02T00:00:00.000Z", "fromName": "Johnny Doe", "fromEmailAddress": "john.doe@example.com", "default": true } }, "eventTime": "2024-01-02T00:00:00.000000000Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "2" }
Did this help?