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.
- 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.
- Don't send the API key by mail: if your email account gets hacked, your data stored at eSputnik will be at risk.