API Keys

What Is an API?

An API is the interface that allows two independent software components to exchange information.

With API keys you can give independent components access to your eSputnik account without transmitting your password.

API Key Usage

Use an API key to set up integration with your eSputnik account.

The key provides access to data from your eSputnik account, so it must be protected from unauthorized access.

The eSputnik API uses Basic HTTP Access Authentication for an API key.

To access your account resources:

• input any value in Username,
• input the value of your API key in Password.

An example of authorization with the API key for Postman:

How to Create and Edit an API Key

You need to generate an API key to set up integration with your eSputnik account.

1. Go to your profile > Settings > API.

2. Click Add key.

3. In Description, enter information about which application or site will use this key to access your account. This will help identify this API key in the future.

4. You can restrict access rights to the risk parts of your account in eSputnik.

5. To set up several integrations, create a key for each of them. You can also create multiple keys with different access rights within one account.

The created API key with the corresponding data will appear in the general list:

• key,
• who created,
• creation date,
• account accesses,
• key description,
• key status (available/not available).

Access Rights

Access to eSputnik resources through an API key is set up at the key creation stage.

You can give full access to all eSputnik API resources and methods by choosing Full access to API. Or you can limit access rights by choosing Access to events or Access to events and contacts:

Available API Methods

The following rules of access to eSputnik resources through an API key apply to all method versions (/ v1, / v2, etc.), unless otherwise specified.

1. Default API Methods

The following methods don't require any special permissions and are available for any option.

Common methods:

GET version

Account information:

GET    account/info
GET    balance
GET    subscriptions
GET    addressbooks

Message management:

POST   messages/email
GET    messages/email
GET    messages/email/{id}
DELETE messages/email/{id}
PUT    messages/email/{id}
DELETE messages/email/{id}/{language}
PUT    messages/email/{id}/{language}
GET    messages/email/{id}/viewLink
GET    messages/sms
GET    messages/sms/{id}

Interface management:

GET    interfaces/email
GET    interfaces/sms

Analytics:

GET    callouts/sms
GET   contact/token/activated/{app_uuid}/{token_id}
PUT   contact/token/activated/{app_uuid}/{token_id}
PUT   interactions/{interaction_id}/status

2. Read contacts and segments

GET contacts
GET contact/{id}
GET contacts/email
GET contact/{id}/subscriptions
GET groups
GET group/{id}/contacts

3. Write contacts and segments

POST contacts
POST contacts/upload
GET  importstatus/{sessionId}
 
POST   contact
PUT    contact/{id}
DELETE contact/{id}
PUT    contact/{id}/subscriptions
POST   contact/subscribe
 
POST emails/unsubscribed/add
POST emails/unsubscribed/delete
POST group/{id}/contacts/detach

4. Manage contact activity in campaigns

GET  contacts/activity

5. Manage events

POST   event
POST   past_events
DELETE past_events

6. Send messages

POST   message/{id}/smartsend
GET    message/status
POST   message/email
POST   message/sms
POST   message/viber
 
POST   broadcast
GET    broadcast/{broadcast_id}
DELETE broadcast/{broadcast_id}
GET    broadcasts

Key Disabling

If the key is compromised, you can disable it by moving the toggle to the Off position. After you confirm your action in the pop-up window, the system will block access to the API with this key. The procedure for unlocking the key is the same. If the key isn't used for 90 days, it is disabled automatically.

Key Deletion

You can permanently delete the key so that it won't be possible to restore it. Click the three dots opposite the key and select Delete in the drop-down list.

API Key Security

The API keys provide access to the data of your eSputnik account and must be as secured as your password. Сonsider the following when working with API keys.

1. The key should not be visible in screenshots or demo videos. Blurring the key may not be enough; it's better to cut it off in a graphical editor.
2. Don't send the API key by mail: if your email account gets hacked, your data stored at eSputnik will be at risk.